Core API（入口、组件、宏）
本页覆盖 wevu 中最先接触的一组 API：应用入口、组件定义、<script setup> 宏与模板工具。每个 API 单独成段，便于按需跳转。
入口与组件定义
createApp()
类型签名： typeof import('wevu')['createApp']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
Vue 差异： Vue Web 创建并挂载 DOM 应用；Wevu 创建的是小程序 App 注册描述，不接收根 DOM 容器，通常每个 App 入口只调用一次。
示例： 见 本组示例。
- 类型入口：
CreateAppOptions/RuntimeApp - 用途：创建并注册小程序 App 运行时入口。
- 说明：通常在 App 侧只调用一次。
defineComponent()
类型签名： typeof import('wevu')['defineComponent']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
DefineComponentOptions/ComponentDefinition - 用途：定义页面/组件并接入 Wevu 生命周期与响应式。
- 说明：Wevu 统一使用
Component()模型。
本组示例
App 入口负责全局初始化，页面和组件继续通过 defineComponent() 组织实例状态。
import { createApp, defineComponent, onShow, ref } from 'wevu'
createApp({
setup() {
return { startedAt: Date.now() }
},
})
export default defineComponent({
setup() {
const visits = ref(0)
onShow(() => visits.value += 1)
return { visits }
},
})应用实例
app.mount()
类型签名： RuntimeApp['mount']
Vue 差异： Vue 接收 DOM 容器；Wevu 接收可选的小程序 MiniProgramAdapter，并返回 RuntimeInstance。
示例： 见 本组示例。
该方法建立响应式状态与小程序 setData 之间的适配。常规小程序入口由 createApp() 自动注册，只有测试或自定义适配器场景通常需要显式调用。
app.unmount()
类型签名： RuntimeApp['unmount']
Vue 兼容说明： 都用于停止应用并执行清理，但 Wevu 不涉及 DOM 根节点移除。
示例： 见 本组示例。
重复调用是安全的；已执行的应用级清理不会再次运行。
app.onUnmount()
类型签名： RuntimeApp['onUnmount']
Vue 兼容说明： 调用方式与 Vue 一致；Wevu 用它管理小程序应用级插件和资源清理。
示例： 见 本组示例。
传入值必须是函数。应用已经卸载时，新登记的清理函数会立即执行。
app.use()
类型签名： RuntimeApp['use']
Vue 兼容说明： 支持函数插件和带 install() 的对象插件，并忽略同一插件的重复安装；插件接收的是 Wevu RuntimeApp。
示例： 见 本组示例。
插件中的 hook 仍需在同步初始化阶段注册，不能在 await 之后补注册生命周期。
app.provide()
类型签名： RuntimeApp['provide']
Vue 兼容说明： 调用方式与 Vue 一致；依赖通过 Wevu 的页面/组件上下文链传递，而不是 DOM 组件树。
示例： 见 本组示例。
返回应用实例，可与 app.use() 链式调用。
app.config
类型定义： AppConfig
Vue 差异： Wevu 当前只公开 globalProperties，不提供 Vue Web 的错误处理器、编译器选项、性能标记和选项合并策略。
示例： 见 本组示例。
不要假设 Vue app.config 的其他字段在 Wevu 中存在。
app.config.globalProperties
类型定义： Record<string, any>
Vue 兼容说明： 用于向组件公开共享属性；最终访问发生在 Wevu 组件公共代理上。
示例： 见 本组示例。
业务状态仍应优先放入 store 或 provide/inject，避免把该对象当成无边界全局状态容器。
app.version
运行时值： string
Vue 兼容说明： 与 Vue 一样用于读取当前框架版本，值对应 Wevu 包版本。
示例： 见 本组示例。
该字段为只读版本信息，不用于运行时能力检测。
version
运行时值： string
Vue 兼容说明： wevu 根入口直接导出版本字符串，与 app.version 保持一致。
示例： 见 本组示例。
适合在诊断信息中展示，不要根据字符串比较切换核心业务逻辑。
本组示例
应用实例适合承载插件安装、全局依赖和应用级清理。
import { createApp, version } from 'wevu'
const app = createApp({})
app
.use(runtimeApp => runtimeApp.provide('apiBase', '/api'))
.onUnmount(() => console.info('dispose app resources'))
console.info(version, app.version)Script Setup 宏
defineProps()
类型签名： typeof import('wevu')['defineProps']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
ComponentPropsOptions/ExtractPropTypes - 用途：声明组件 props。
- 说明：支持对象写法与 TS 泛型写法。
withDefaults()
类型签名： typeof import('wevu')['withDefaults']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
ExtractDefaultPropTypes - 用途：给类型化 props 设置默认值。
- 说明：通常与
defineProps<T>()配套。
defineEmits()
类型签名： typeof import('wevu')['defineEmits']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
EmitsOptions/TriggerEventOptions - 用途：声明事件与参数类型。
- 说明：支持对象/数组/泛型（含 named tuple）。
defineSlots()
类型签名： typeof import('wevu')['defineSlots']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
VNode - 用途：声明 slots 类型。
defineExpose()
类型签名： typeof import('wevu')['defineExpose']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
ComponentPublicInstance - 用途：显式暴露实例字段。
defineModel()
类型签名： typeof import('wevu')['defineModel']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
ModelBinding - 用途：声明
v-model绑定。
defineOptions()
类型签名： typeof import('wevu')['defineOptions']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
MiniProgramComponentOptions - 用途：在
<script setup>中定义组件配置项。 - Behavior 说明：可直接声明
behaviors。当条目来自原生Behavior()返回值时，编译阶段会保留该表达式并继续后续转换。 - 字段分层：
- 放进
options的是原生ComponentOptions字段，例如multipleSlots、styleIsolation、virtualHost - 组件顶层字段例如
externalClasses、behaviors、relations，直接写在defineOptions({ ... })顶层
- 放进
示例：
<script setup lang="ts">
defineOptions({
externalClasses: ['custom-class'],
options: {
virtualHost: true,
styleIsolation: 'apply-shared',
},
})
</script>definePageMeta()
类型签名： typeof import('wevu')['definePageMeta']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
PageMeta/PageLayoutMeta - 用途：在
<script setup>中声明页面级元信息。 - 说明：常用于声明页面
layout，与 Weapp-vite 的自动路由、routeRules.layout和运行时setPageLayout()保持同一套页面壳心智。
示例：
<script setup lang="ts">
definePageMeta({
layout: 'default',
})
</script>defineAppSetup()
类型签名： typeof import('wevu')['defineAppSetup']
运行时说明： 这是 <script setup> 编译期宏，无需从 wevu 导入，也不能作为普通运行时函数动态调用。
示例： 见 本组示例。
- 类型入口：
RuntimeApp - 用途：声明 App 级 setup 初始化逻辑。
- 说明：适合把插件安装、全局 provide、全局 router 初始化等 App 级逻辑收敛到一个同步入口。
defineAppJson()
类型签名： typeof import('weapp-vite/json')['defineAppJson']
运行时说明： 在 app.vue 中作为顶层编译宏使用时，配置会被提取并合并到 app.json，运行时零开销。
示例： 见 本组示例。
支持直接对象或接收编译上下文的函数；一个 App SFC 应只保留一套 App JSON 声明。
definePageJson()
类型签名： typeof import('weapp-vite/json')['definePageJson']
运行时说明： 在页面 SFC 中提取为页面 JSON，可与 definePageMeta() 分别声明宿主配置和布局元信息。
示例： 见 本组示例。
常用于导航栏、下拉刷新和 usingComponents 等页面配置。
defineComponentJson()
类型签名： typeof import('weapp-vite/json')['defineComponentJson']
运行时说明： 在组件 SFC 中提取为组件 JSON，并参与原生组件注册与选项合并。
示例： 见 本组示例。
组件角色只使用该宏，不要与页面或 App JSON 宏混用。
defineSitemapJson()
类型签名： typeof import('weapp-vite/json')['defineSitemapJson']
编译期说明： 这是 weapp-vite/json 导出的类型安全配置辅助函数，不是 Vue SFC 自动提取宏。
示例： 见 本组示例。
它返回原配置，适合在独立 sitemap 配置模块中获得结构类型提示。
defineThemeJson()
类型签名： typeof import('weapp-vite/json')['defineThemeJson']
编译期说明： 这是 weapp-vite/json 导出的主题配置辅助函数，不是 Vue SFC 自动提取宏。
示例： 见 本组示例。
它用于约束 theme 配置结构，本身不注册 Wevu 运行时能力。
本组示例
页面 SFC 中直接使用对应角色的 JSON 宏，无需保留额外 <json> 块。
<script setup lang="ts">
definePageJson({
navigationBarTitleText: '订单',
enablePullDownRefresh: true,
})
definePageMeta({ layout: 'default' })
</script>use()
类型签名： typeof import('wevu')['use']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
WevuPlugin - 用途：安装 Wevu 插件。
- 说明：可在 App setup 或受控初始化逻辑中使用；插件如果需要注册 hook，仍必须保持同步注册。
mergeModels()
类型签名： typeof import('wevu')['mergeModels']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
ModelBindingPayload - 用途：合并多路 model 绑定结果。
useModel()
类型签名： typeof import('wevu')['useModel']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
ModelBinding - 用途：运行时读取/写入某个 model。
本组示例
相关宏可以在一个组件中共同声明类型、默认值、事件和 model。
<script setup lang="ts">
interface Props { title?: string }
defineOptions({ options: { virtualHost: true } })
const props = withDefaults(defineProps<Props>(), { title: '未命名' })
const emit = defineEmits<{ submit: [title: string] }>()
const model = defineModel<number>({ default: 0 })
defineExpose({ submit: () => emit('submit', props.title) })
</script>模板工具
useAttrs()
类型签名： typeof import('wevu')['useAttrs']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
SetupContext - 用途：获取透传属性 attrs。
useSlots()
类型签名： typeof import('wevu')['useSlots']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
TemplateRefs - 用途：读取 slots。
useTemplateRef()
类型签名： typeof import('wevu')['useTemplateRef']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
TemplateRef/TemplateRefValue - 用途：读取模板 ref 对应实例。
useNativeInstance()
- 类型入口：
SetupContextNativeInstance - 用途：在 setup 中访问原生页面/组件实例。
useNativeRouter()
- 类型入口：
WechatMiniprogram.Component.Router - 用途：获取组件路径语义的路由器对象。
- 说明：优先命中实例
router，然后回退pageRouter，低版本基础库再降级到全局wx/my/tt路由方法。
useNativePageRouter()
- 类型入口：
WechatMiniprogram.Component.Router - 用途：获取页面路径语义的路由器对象。
- 说明：优先命中实例
pageRouter，然后回退router，低版本基础库再降级到全局wx/my/tt路由方法。
normalizeClass()
类型签名： typeof import('wevu')['normalizeClass']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
string - 用途：归一化 class 输入（对象/数组/字符串）。
normalizeStyle()
类型签名： typeof import('wevu')['normalizeStyle']
运行时说明： 该 API 运行在 Wevu 的组件作用域内；涉及 hook 或实例上下文时，应在同步 setup() 中调用。
示例： 见 本组示例。
- 类型入口：
string - 用途：归一化 style 输入。
本组示例
原生实例和模板 ref 只在方法中使用，不要把它们返回为模板可序列化状态。
<script setup lang="ts">
import { normalizeClass, useAttrs, useNativeInstance, useTemplateRef } from 'wevu'
const attrs = useAttrs()
const panel = useTemplateRef('panel')
const native = useNativeInstance()
const panelClass = normalizeClass(['panel', { highlighted: attrs.highlighted }])
function inspectPanel() {
console.log(panel.value, native)
}
</script>