Weapp-vite

Appearance

Lifecycle API（生命周期） ​

以下条目严格对应 packages-runtime/wevu/src/runtime/hooks.ts 的导出函数。所有 Hook 都要求在 setup() 同步阶段调用。

App 生命周期 Hook ​

onLaunch() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App
  • 源码行为：注册到 onLaunch。

onShow() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App / Page / Component
  • 源码行为：统一注册到 onShow（App 与页面/组件共用函数名）。

onHide() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App / Page / Component
  • 源码行为：统一注册到 onHide。

onError() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App / Component
  • 源码行为：注册到 onError。

onPageNotFound() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App
  • 源码行为：注册到 onPageNotFound。

onUnhandledRejection() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App
  • 源码行为：注册到 onUnhandledRejection。

onThemeChange() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App
  • 源码行为：注册到 onThemeChange。

onMemoryWarning() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：App
  • 源码行为：通过 wx.onMemoryWarning 注册监听，并在重复绑定时自动调用 wx.offMemoryWarning 清理旧监听。
  • 建议：回调内优先释放大缓存、长列表临时数据与不必要的订阅/定时器。

本组示例 ​

App hook 同样必须在同步 setup() 中注册。

ts
import { createApp, onError, onLaunch, onMemoryWarning, onShow } from 'wevu'

createApp({
  setup() {
    onLaunch(options => console.log('launch', options))
    onShow(options => console.log('show', options))
    onError(error => console.error(error))
    onMemoryWarning(({ level }) => console.warn('memory', level))
  },
})

页面生命周期 Hook ​

onLoad() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：注册到页面 onLoad。

onReady() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page / Component
  • 源码行为：注册到 onReady；组件通过 lifetimes.ready 触发。

onUnload() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page / Component
  • 源码行为：在页面 onUnload 或组件 teardown 时统一触发。

本组示例 ​

先同步注册 hook，再在回调内部执行异步工作。

vue
<script setup lang="ts">
import { onLoad, onReady, onUnload } from 'wevu'

let timer: ReturnType<typeof setInterval> | undefined

onLoad(query => console.log('query', query))
onReady(() => {
  timer = setInterval(() => {}, 1000)
})
onUnload(() => {
  if (timer) {
    clearInterval(timer)
  }
})
</script>

页面事件 Hook ​

onPullDownRefresh() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：注册到页面 onPullDownRefresh。

onReachBottom() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：注册到页面 onReachBottom。

onPageScroll() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：注册到页面 onPageScroll。

onRouteDone() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page / Component
  • 源码行为：注册到 onRouteDone；组件通过 pageLifetimes.routeDone 桥接触发。

onTabItemTap() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：注册到页面 onTabItemTap。

onResize() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page / Component
  • 源码行为：注册到 onResize；组件通过 pageLifetimes.resize 桥接触发。

本组示例 ​

高频滚动回调只更新必要状态，耗时请求放在低频事件中。

vue
<script setup lang="ts">
import { onPageScroll, onPullDownRefresh, onReachBottom, ref } from 'wevu'

const scrollTop = ref(0)
onPageScroll((event) => {
  scrollTop.value = event.scrollTop
})
onReachBottom(() => loadNextPage())
onPullDownRefresh(async () => {
  await reloadList()
  wx.stopPullDownRefresh()
})
</script>

返回值型页面 Hook ​

onShareAppMessage() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：单实例 Hook（single: true），返回值用于分享配置。

onShareTimeline() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：单实例 Hook（single: true），返回值用于朋友圈分享配置。

onAddToFavorites() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：单实例 Hook（single: true），返回值用于收藏配置。

onSaveExitState() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Page
  • 源码行为：单实例 Hook（single: true），返回值用于退出状态保存。

本组示例 ​

返回值直接交给小程序宿主，字段结构应遵循对应平台契约。

vue
<script setup lang="ts">
import { onAddToFavorites, onShareAppMessage, onShareTimeline } from 'wevu'

onShareAppMessage(() => ({ title: '商品详情', path: '/pages/goods/index?id=42' }))
onShareTimeline(() => ({ title: '商品详情', query: 'id=42' }))
onAddToFavorites(() => ({ title: '商品详情', query: 'id=42' }))
</script>

组件扩展 Hook ​

onAttached() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Component
  • 源码行为：在组件 lifetimes.attached 阶段触发。

onDetached() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Component
  • 源码行为：在组件 lifetimes.detached 阶段触发。

onMoved() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

示例： 见 本组示例。

  • 作用域：Component
  • 源码行为：注册到 lifetimes.moved。

本组示例 ​

组件资源在 attached 后创建，并在 detached 中释放。

vue
<script setup lang="ts">
import { onAttached, onDetached, onMoved } from 'wevu'

let observer: WechatMiniprogram.IntersectionObserver | undefined

onAttached(() => {
  observer = wx.createIntersectionObserver()
})
onMoved(() => console.log('component moved'))
onDetached(() => {
  observer?.disconnect()
})
</script>

Vue 语义对齐 Hook ​

onBeforeMount() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 没有 DOM mount 阶段；该回调发生在小程序实例已创建、首次宿主渲染提交之前。

示例： 见 本组示例。

  • 对齐语义：Vue beforeMount
  • 源码行为：在 setup() 内同步立即执行。

onMounted() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 对应宿主 ready，不是浏览器 DOM 插入完成；此时才适合执行节点查询。

示例： 见 本组示例。

  • 对齐语义：Vue mounted
  • 源码行为：映射到 onReady。

onBeforeUpdate() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 围绕 Wevu 即将提交的 setData 批次触发，而不是 Virtual DOM patch。

示例： 见 本组示例。

  • 对齐语义：Vue beforeUpdate
  • 源码行为：映射到内部 __wevuOnBeforeUpdate。

onUpdated() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 在当前 setData 更新批次完成后触发，不能据此假设浏览器布局或 requestAnimationFrame 语义。

示例： 见 本组示例。

  • 对齐语义：Vue updated
  • 源码行为：映射到内部 __wevuOnUpdated。

onBeforeUnmount() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 对应页面卸载或组件移除前的清理阶段，不涉及 DOM unmount。

示例： 见 本组示例。

  • 对齐语义：Vue beforeUnmount
  • 源码行为：在 setup() 内同步立即执行（小程序无对应原生 before-unmount）。

onUnmounted() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 对应宿主 detached/页面卸载后的销毁阶段。

示例： 见 本组示例。

  • 对齐语义：Vue unmounted
  • 源码行为：映射到 onUnload。

onActivated() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 映射到页面或组件重新可见的宿主生命周期，不依赖 Vue <KeepAlive>。

示例： 见 本组示例。

  • 对齐语义：Vue activated
  • 源码行为：映射到 onShow。

onDeactivated() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 映射到宿主隐藏阶段，不表示 <KeepAlive> 缓存树被停用。

示例： 见 本组示例。

  • 对齐语义：Vue deactivated
  • 源码行为：映射到 onHide。

onErrorCaptured() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 捕获 Wevu setup、渲染和宿主生命周期链路中的错误，不具备完整 Vue 组件树错误传播语义。

示例： 见 本组示例。

  • 对齐语义：Vue errorCaptured
  • 源码行为：映射到 onError 包装调用。

onServerPrefetch() ​

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

运行时说明： 必须在同步 setup() 阶段注册，运行时才能把回调绑定到当前 App、页面或组件实例；不要在 await 之后注册。

Vue 差异： 小程序没有 SSR；为迁移兼容保留该 hook，但运行时不会执行预取。

示例： 见 本组示例。

  • 对齐语义：Vue serverPrefetch
  • 源码行为：保留 API 形态，仅做调用时机校验，不执行实际逻辑。

本组示例 ​

这些名称接近 Vue，但时机围绕宿主 ready、setData 和 detached。

vue
<script setup lang="ts">
import { onBeforeUpdate, onMounted, onServerPrefetch, onUnmounted, onUpdated } from 'wevu'

onMounted(() => console.log('宿主 ready，可开始节点查询'))
onBeforeUpdate(() => console.log('setData 提交前'))
onUpdated(() => console.log('setData 批次完成'))
onUnmounted(() => console.log('宿主实例已销毁'))

// 小程序没有 SSR，这个兼容 hook 不会执行。
onServerPrefetch(async () => {})
</script>

小程序原生生命周期映射（说明） ​

以下是桥接关系说明，不是 wevu 直接导出的 Hook API。

lifetimes.created ​

  • 映射：组件初始化桥接（无独立 onCreated 导出）。

lifetimes.attached ​

  • 映射：组件挂载流程（可使用 onAttached；onMounted 仍映射 onReady）。

lifetimes.ready ​

  • 映射：onReady。

lifetimes.moved ​

  • 映射：onMoved。

lifetimes.detached ​

  • 映射：组件 teardown（可使用 onDetached）+ onUnload 钩子链（含 onUnmounted）。

lifetimes.error ​

  • 映射：onError。

pageLifetimes.show ​

  • 映射：onShow。

pageLifetimes.hide ​

  • 映射：onHide。

pageLifetimes.resize ​

  • 映射：onResize。

pageLifetimes.routeDone ​

  • 映射：onRouteDone。

Released under the MIT License.

Copyright © 2024-present sonofmagic