@mini-dev/event-hook

@mini-dev/event 的可选伴生包 —— 提供一个符合 @mini-dev/hook 协议的 Page decoration，把一个事件作用域注入为 this.$events，并把页面 onShow/onHide/onUnload 自动接到它的 activate/deactivate/dispose。

@mini-dev/event 核心只提供作用域与显式的活跃态转移方法（activate/deactivate/dispose），不接管生命周期。本包把「小程序页面生命周期 → scope 转移方法」这条接线做成一个 @mini-dev/hook decoration，让你一次配置、全页面生效。本包不 import 也不调用 @mini-dev/hook、不改写任何页面实例的方法（零猴补丁）：接线完全经 @mini-dev/hook 的 decoration 机制完成，由你自己决定叠加到哪个构造器、以什么顺序 .use。

目录

1. 安装
2. 用法
3. API 参考
4. 工作原理
5. 注意事项

1. 安装

npm install @mini-dev/event @mini-dev/event-hook @mini-dev/hook

本包的运行时依赖只有 @mini-dev/event；@mini-dev/hook 是 peerDependency（^0.5.3）—— 由你的项目直接依赖并持有，本包只产出一个交给它的 decoration。发布产物为双格式（dist/cjs / dist/esm），miniprogram 指向 dist/cjs。

2. 用法

由你自己持有 _Page（或任意 create(Page) 实例）并叠加本包的 decoration：

// app.js
const { _Page } = require('@mini-dev/hook');
const { createPageEventHook } = require('@mini-dev/event-hook');

_Page.use(createPageEventHook());  // 注册与顺序由你掌握
_Page.mount();                     // 用 _Page 替换全局 Page（或在页面里用 _Page({...})）

App({});

之后任意页面直接用 this.$events，生命周期已自动接线：

// 页面 A：订阅（隐藏时挂起、重新可见时补投最新、卸载时自动退订）
Page({
    data: { last: '未收到' },
    onLoad() {
        this.$events.on('demo:ping', (v) => this.setData({ last: '收到 ' + v }));
    }
    // 无需手写 onShow/onHide/onUnload：decoration 会为缺失的生命周期方法自动合成并接线
});

// 页面 B：只广播
Page({
    fire() {
        this.$events.emit('demo:ping', Date.now());
        wx.navigateBack();
    }
});

因为 createPageEventHook() 只是一个 decoration，它能和你其它的 _Page.use(...) 自由组合，也能用在自建实例上：

const { create } = require('@mini-dev/hook');
const MyPage = create(Page);
MyPage.use(createPageEventHook());
MyPage.use(myOtherDecoration);   // 与你自己的增强共存，顺序自定

this.$events 是一个 EventScope，具备 on / once / emit / activate / deactivate / dispose（后三者已由本 decoration 接到页面生命周期，通常无需手动调用）。投递语义详见 @mini-dev/event 的核心概念。

3. API 参考

3.1 createPageEventHook(options?)

返回一个 @mini-dev/hook 的 Page decoration，覆盖 onLoad/onShow/onHide/onUnload，供你 _Page.use(...)。

function createPageEventHook(options?: { hub?: EventHub; prop?: string }): PageDecoration;

| 选项 | 默认 | 说明 | | --- | --- | --- | | hub | @mini-dev/event 的共享单例 events | 要注入的总线实例；传入自建的 createEventHub() 可用独立总线 | | prop | '$events' | 注入到 Page 实例的属性名，冲突时可改名 |

decoration 各生命周期的动作：

| 生命周期 | 动作 | | --- | --- | | onLoad（before） | this[prop] = hub.scope()（仅当尚未注入）| | onShow（before） | this[prop].activate() | | onHide（before） | this[prop].deactivate() | | onUnload（before） | this[prop].dispose() |

// 自定义总线与属性名
const { createEventHub } = require('@mini-dev/event');
const myHub = createEventHub();
_Page.use(createPageEventHook({ hub: myHub, prop: '$myEvents' })); // 之后用 this.$myEvents

4. 工作原理

sequenceDiagram
    participant App as app.js
    participant Page as _Page (@mini-dev/hook)
    participant Deco as createPageEventHook()
    participant Inst as Page 实例
    App->>Deco: createPageEventHook(options)
    Deco-->>App: 返回覆盖四生命周期的 decoration
    App->>Page: _Page.use(decoration)
    Note over Inst: 页面创建
    Page->>Inst: onLoad before: this.$events = hub.scope()
    Page->>Inst: onShow before: this.$events.activate()（补投）
    Page->>Inst: onHide before: this.$events.deactivate()（挂起）
    Page->>Inst: onUnload before: this.$events.dispose()（退订）

createPageEventHook 返回的 decoration，在 onLoad 前置钩子注入 this[prop] = hub.scope()，并把 onShow/onHide/onUnload 前置钩子分别接到该 scope 的 activate/deactivate/dispose。@mini-dev/hook 会为页面未定义的生命周期方法自动合成，因此即使页面只写了 onLoad（甚至什么都没写），接线依然完整。本包只负责产出 decoration，.use 的调用、注册顺序、作用于哪个构造器都由你决定。

5. 注意事项

5.1 由你掌控 .use 与构造器

本包不 import、不调用 @mini-dev/hook，也不假设全局 _Page。你需要自己 require('@mini-dev/hook') 拿到 _Page（或 create(Page) 自建实例）并调用 .use(createPageEventHook())；页面走被 hook 的构造器（_Page.mount() 替换全局 Page，或在页面里直接用 _Page({...})）。

5.2 与你自己的 hook 组合

createPageEventHook() 是一个普通 decoration，可与你其它 _Page.use(...) 自由叠加，顺序由你决定；scope 的活跃态转移由本 decoration 接线，不与你在同名生命周期上的增强冲突（各自的 before 依次执行）。

5.3 运行环境

@mini-dev/hook 面向小程序运行时（依赖 App / Page 全局），因此叠加了本 decoration 的构造器只在小程序运行时（或开发者工具）中运行。本包自身不 import @mini-dev/hook、不含其运行时副作用，可在任意环境按普通对象工厂使用。