Runtime Bridge API（运行时配置）

本页聚焦可在业务工程中直接使用的运行时能力。内部注册与调度函数已从文档目录中移除。

全局默认值

setWevuDefaults()

类型签名： typeof import('wevu')['setWevuDefaults']

运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。

示例： 见 本组示例。

• 类型入口：WevuDefaults
• 用途：配置 createApp/defineComponent 的默认行为。

resetWevuDefaults()

类型签名： typeof import('wevu')['resetWevuDefaults']

运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。

示例： 见 本组示例。

• 类型入口：void
• 用途：重置默认配置。
• 场景：测试隔离、开发调试。

本组示例

全局默认值按 App 和 Component 分开配置，测试后应重置。

import { resetWevuDefaults, setWevuDefaults } from 'wevu'

setWevuDefaults({
  component: {
    setData: { autoSetDataPick: true },
    options: { multipleSlots: true },
  },
})

afterEach(() => resetWevuDefaults())

setData 排除标记

markNoSetData()

类型签名： typeof import('wevu')['markNoSetData']

运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。

示例： 见 本组示例。

• 类型入口：<T>(value: T) => T
• 用途：标记对象不参与 setData 快照同步。

isNoSetData()

类型签名： typeof import('wevu')['isNoSetData']

运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。

示例： 见 本组示例。

• 类型入口：boolean
• 用途：判断对象是否被标记为 no-setData。

本组示例

原生实例和 SDK 对象不应进入模板快照，可以显式排除。

import { isNoSetData, markNoSetData, reactive } from 'wevu'

const player = markNoSetData(wx.createVideoContext('player'))
const state = reactive({ title: '视频详情', player })

console.log(isNoSetData(state.player))

调试记录

addMutationRecorder()

类型签名： typeof import('wevu')['addMutationRecorder']

运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。

示例： 见 本组示例。

• 类型入口：MutationRecord
• 用途：注册状态 mutation 记录器。

removeMutationRecorder()

类型签名： typeof import('wevu')['removeMutationRecorder']

运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。

示例： 见 本组示例。

• 类型入口：MutationRecord
• 用途：移除状态 mutation 记录器。

本组示例

Recorder 用同一个函数引用注册和移除，避免调试监听残留。

import type { MutationRecord } from 'wevu'
import { addMutationRecorder, removeMutationRecorder } from 'wevu'

const recorder = (record: MutationRecord) => console.log(record)
addMutationRecorder(recorder)

// 调试结束或实例卸载时清理。
removeMutationRecorder(recorder)

页面布局桥接

setPageLayout() / usePageLayout()

• 类型入口：PageLayoutState / WevuPageLayoutMap
• 用途：在运行时读取或切换页面 layout。
• 说明：通常由 Weapp-vite 的 definePageMeta({ layout })、routeRules.layout 先确定初始 layout；业务侧只在需要运行时切换页面壳时调用。

registerPageLayoutBridge() / unregisterPageLayoutBridge()

• 类型入口：LayoutBridgeInstance
• 用途：注册页面 layout 桥接实例。
• 说明：主要给 Weapp-vite layout 运行时与框架集成使用，业务工程通常不需要直接调用。

registerRuntimeLayoutHosts() / unregisterRuntimeLayoutHosts()

• 类型入口：LayoutHostBinding
• 用途：注册 layout host 映射，供页面运行时定位当前页面壳。
• 说明：属于框架集成层 API；业务侧优先使用 setPageLayout()。

useLayoutBridge() / useLayoutHosts()

• 类型入口：LayoutBridgeInstance / LayoutHostBinding
• 用途：读取当前 layout bridge 或 host 绑定。
• 说明：用于 layout 组件、调试页和框架扩展，不建议普通页面直接依赖。

resolveLayoutBridge()

• 类型入口：LayoutBridgeInstance
• 用途：解析当前页面已注册的 layout bridge。
• 适合：需要在业务 hook 中统一访问 layout 内部宿主能力时，先定位承载宿主组件的 layout 上下文。
• 说明：普通业务页面优先使用更直接的 resolveLayoutHost()；只有需要自己调用 selectComponent() 或做兼容兜底时再使用 bridge。

resolveLayoutHost() / waitForLayoutHost()

• 类型入口：LayoutHostResolveOptions
• 用途：按 layout-host key 解析 layout 内暴露的宿主组件实例。
• 适合：Toast、Dialog、全局反馈层、抽屉等天然属于 layout 的组件。
• 说明：resolveLayoutHost() 同步返回当前可用实例；waitForLayoutHost() 会按短间隔重试，适合页面初次进入时等待 layout 宿主完成挂载。

示例：

<script setup lang="ts">
import { resolveLayoutHost } from 'wevu'

interface ToastHost {
  show: (options: { message: string }) => void
}

function showSuccess() {
  const toast = resolveLayoutHost<ToastHost>('layout-toast')
  toast?.show({ message: '操作成功' })
}
</script>

子路径边界

• wevu/compiler 不是 wevu 根入口的一部分，主要给编译工具使用。
• wevu/router 也不是运行时桥接页的一部分；若你需要 createRouter() / useRouter()，请直接看 /wevu/router。
• wevu/fetch 与 wevu/web-apis 是网络/Web API 兼容入口；分别看 /wevu/fetch 与 Web runtime 相关说明。