uni-lifecycle

为 uni-app 提供的页面生命周期钩子注册与参数获取工具，解决在 NPM 包/插件中无法直接导入 @dcloudio/uni-app 钩子的问题，让插件开发者能够安全、便捷地注册页面生命周期回调，并优雅地获取生命周期参数。

特性

• ✅ 插件友好 – 可在任何 NPM 包内注册页面生命周期钩子，无构建报错
• ✅ 双模式 API – 支持注册回调 Lifecycle.onLoad(fn) 和直接获取参数 await Lifecycle.onLoad.getParams()
• ✅ 自动参数解包 – 单参数自动返回该值，多参数返回数组（保护未来兼容性）
• ✅ 页面实例隔离 – 每个页面的钩子独立存储，页面销毁后自动回收
• ✅ 保留原始钩子 – 包装用户钩子时不破坏页面原有生命周期逻辑
• ✅ TypeScript 支持 – 完整的类型定义

适用场景

• 开发 uni-app 插件（路由、埋点、权限、UI 库等），需要在页面生命周期中注入逻辑
• 希望在应用中全局管理页面生命周期，避免在每个页面手动编写重复代码
• 需要异步等待 onLoad 参数（例如路由传参自动注入）

安装

pnpm add uni-lifecycle

快速上手

注册生命周期回调

import { Lifecycle } from 'uni-lifecycle';

// 页面加载时执行
Lifecycle.onLoad((query) => {
  console.log('页面参数', query);
});

// 页面显示时执行（每次显示都会触发）
Lifecycle.onShow(() => {
  console.log('页面显示了');
});

获取生命周期参数

// 等待 onLoad 参数（Promise 会在当前页面的 onLoad 触发后 resolve）
const query = await Lifecycle.onLoad.getParams();
console.log(query); // { id: 123, ... }

// 获取 onShow 参数（onShow 无参数，返回 undefined）
const showArg = await Lifecycle.onShow.getParams();

在插件中使用（典型场景）

// 你的插件内部
import { Lifecycle } from 'uni-lifecycle';

export function initTracker() {
  // 自动埋点页面访问
  Lifecycle.onLoad(() => {
    reportPageView();
  });
}

与路由库配合（自动注入参数）

// 路由库内部实现 useQuery
import { Lifecycle } from 'uni-lifecycle';

export async function useQuery(key?: string) {
  const query = await Lifecycle.onLoad.getParams();
  return key ? query?.[key] : query;
}

API 参考

Lifecycle

所有页面生命周期方法都支持两种调用形式：

• Lifecycle.onLoad(fn: Function): void – 注册回调
• Lifecycle.onLoad.getParams(): Promise<any> – 等待并获取参数

支持的生命周期列表（与 uni-app 页面生命周期一致）：

• onLoad
• onShow
• onHide
• onReady
• onResize
• onRouteDone
• onUnload

参数返回值规则

• 如果生命周期回调只有一个参数（如 onLoad(query)），getParams() 直接返回该参数对象。
• 如果生命周期回调无参数（如 onShow()），getParams() 返回 undefined。
• 如果将来出现多参数生命周期，getParams() 返回完整数组。

注意事项

1. 调用时机 – 注册钩子或调用 getParams 时，确保页面栈中存在当前页面（即已在页面上下文中）。通常在页面的 setup、onLoad 之前调用即可，getParams 内部会等待直到生命周期触发。
2. 页面切换 – getParams 基于调用时刻的当前页面等待，不会受到后续页面跳转的影响。
3. 内存管理 – 每个页面的钩子相互隔离，页面卸载时自动回收，无需手动清理。
4. TypeScript – 包自带类型定义，无需额外安装 @types。