vue-page-store 0.4.1 → 0.5.0

package/README.md

@@ -17,6 +17,7 @@
 - **enter / leave** — 页面可见性生命周期
 - **$setInterval** — 页面级定时器托管
 - **event bus** — 页面内作用域通信
+- **plugin** — 外部扩展机制（v0.5 新增）
 
 页面离开时可以自动清理页面级定时器，页面销毁时 `$destroy` 一键回收，不污染全局。
 
@@ -176,6 +177,11 @@ export default {
 | `init` | `function` | store 创建后一次性调用，`$vm` 已可用。适合拉字典、注册事件监听 |
 | `enter` | `function` | 页面进入可见 / 可交互状态时触发 |
 | `leave` | `function` | 页面离开可见 / 可交互状态时触发 |
+| *其它字段* | *any* | 注册过的 plugin 可声明自己的字段（见 [Plugin](#plugin)） |
+
+### `registerPlugin(plugin)` *(v0.5 新增)*
+
+注册全局插件，详见 [Plugin](#plugin) 节。
 
 ### Store 实例属性与方法
 
@@ -260,24 +266,29 @@ v0.4.1 新增 `init`，用于 store 创建后的一次性初始化。
 created() 开始
   └→ useStore(this)
        └→ createStoreInstance()   ← state/source/getters/actions 就绪
+       └→ plugin.install()        ← v0.5：plugin 安装（$vm 尚未绑定）
        └→ bindTo(this)            ← $vm 赋值
        └→ ★ init()               ← $vm 可用，只执行一次
   └→ created() 剩余代码
 mounted()
   └→ ★ enter()                   ← DOM 就绪，每次可见都执行
+  └→ plugin.enter()              ← v0.5：plugin enter 钩子
 
 --- keep-alive 切走 ---
 deactivated()
   └→ clearAllIntervals()
   └→ ★ leave()
+  └→ plugin.leave()              ← v0.5：plugin leave 钩子
 
 --- keep-alive 切回 ---
 activated()
   └→ ★ enter()                   ← 重新开轮询、刷数据
+  └→ plugin.enter()
 
 --- 页面销毁 ---
 beforeDestroy()
   └→ ★ leave()（如果还没 leave）
+  └→ plugin.destroy()            ← v0.5：plugin destroy 钩子
   └→ $destroy()
 ```
 
@@ -419,6 +430,128 @@ state: () => ({
 })
 ```
 
+## Plugin
+
+*v0.5 新增。* Plugin 机制让外部库可以给 `definePageStore` options 增加**新字段**并消费它，同时挂钩 enter / leave / destroy 生命周期——而不需要修改 page-store 本身。
+
+> 典型场景：`vue-page-runtime`（请求编排）、`vue-page-persist`（状态持久化）、devtools 扩展。
+
+### 协议
+
+Plugin 是一个对象，包含 `name` 和 `install`：
+
+```js
+{
+  name: 'tasks',                          // 同时作为 options 字段匹配键
+  install(store, fieldValue, { Vue }) {   // fieldValue === options.tasks
+    // 初始化 plugin 自己的逻辑
+    return {
+      enter()   { /* page enter 后调用 */ },
+      leave()   { /* page leave 后调用 */ },
+      destroy() { /* store 销毁时调用 */ },
+    }
+  }
+}
+```
+
+- **匹配规则**：`options[plugin.name] !== undefined` 才会调用 `install`。没有声明字段的 store 完全不受影响。
+- **install 时机**：store 创建末尾，state / getters / actions / $source / $setInterval / $emit 等全部就绪。`$vm` 此时**尚未**绑定。
+- **返回值**：可选 `{ enter?, leave?, destroy? }`。不需要钩子可以不返回。
+
+### 注册
+
+全局注册一次即可：
+
+```js
+// main.js
+import { registerPlugin } from 'vue-page-store'
+import taskPlugin from 'vue-page-runtime/plugin'
+
+registerPlugin(taskPlugin)
+```
+
+之后正常写 store，声明插件字段：
+
+```js
+import { definePageStore } from 'vue-page-store'   // 入口不变
+
+definePageStore('order', {
+  state: () => ({ /* ... */ }),
+
+  // page-store 不认识这个字段，但会递给注册过的 plugin
+  tasks: {
+    fetchUser: {
+      trigger: 'enter',
+      async run() { return api.getUser(this.$vm.$route.params.id) },
+    },
+    fetchOrders: {
+      deps: ['fetchUser'],
+      async run() { /* ... */ },
+    },
+  },
+})
+```
+
+### 写一个 plugin
+
+最小示例——一个把 `persist` 字段声明持久化到 localStorage 的插件：
+
+```js
+const persistPlugin = {
+  name: 'persist',
+
+  install(store, fieldValue /* options.persist */, { Vue }) {
+    const { key, paths } = fieldValue
+
+    // 恢复
+    try {
+      const saved = JSON.parse(localStorage.getItem(key) || '{}')
+      store.$patch(saved)
+    } catch (e) {}
+
+    // 持久化 —— 监听指定字段
+    const stopWatchers = paths.map(p =>
+      store._vm.$watch(
+        () => store[p],
+        (val) => {
+          const cur = JSON.parse(localStorage.getItem(key) || '{}')
+          cur[p] = val
+          localStorage.setItem(key, JSON.stringify(cur))
+        }
+      )
+    )
+
+    return {
+      destroy() {
+        stopWatchers.forEach(stop => stop())
+      }
+    }
+  }
+}
+
+registerPlugin(persistPlugin)
+```
+
+使用：
+
+```js
+definePageStore('page', {
+  state: () => ({ keyword: '', filters: {} }),
+  persist: {
+    key: 'page:cache',
+    paths: ['keyword', 'filters']
+  }
+})
+```
+
+### 注意事项
+
+- **全局注册，影响所有 store**。plugin 只在对应 store 声明了 `options[plugin.name]` 时才激活，但注册本身是全局的。
+- **同名 plugin 只能注册一次**，重复注册会被跳过并打印 warning。
+- **install 返回的钩子会被按注册顺序依次调用**（FIFO）。
+- **plugin 之间不通信**。如果两个 plugin 有依赖关系，应该合并成一个。
+- **$vm 在 install 时为 null**。如果 plugin 需要组件实例，应在 `enter` 钩子里访问（此时 `$vm` 已绑定）。
+
 ## 实例模型：Singleton
 
 当前版本采用 **id → singleton** 模型：
@@ -471,17 +604,43 @@ actions: {
 
 ## 调试
 
-`storeRegistry` 是导出的 Map，可以在控制台直接查看：
+### `storeRegistry` —— 导出的 Map
+
+`storeRegistry` 是导出的 Map，可以在代码里用于调试或自定义 devtools 集成：
 
 ```js
 import { storeRegistry } from 'vue-page-store'
 
-// 查看所有活跃 store
 storeRegistry.forEach((store, id) => {
   console.log(id, store.$status, store.$disposed)
 })
 ```
 
+### `window.__VUE_PAGE_STORE__` —— dev 自动挂载 *(v0.5 新增)*
+
+开发环境下（`process.env.NODE_ENV !== 'production'`）会自动挂到 `window.__VUE_PAGE_STORE__`，方便控制台访问。生产环境和 SSR 环境不会挂。
+
+控制台用法：
+
+```js
+__VUE_PAGE_STORE__                        // { registry, stores }
+__VUE_PAGE_STORE__.stores                 // { orderList: {…}, userProfile: {…} }
+__VUE_PAGE_STORE__.stores.orderList       // ← 有属性自动补全
+__VUE_PAGE_STORE__.stores.orderList.$source
+__VUE_PAGE_STORE__.stores.orderList.$loading
+
+// 原始 Map 也保留
+__VUE_PAGE_STORE__.registry.forEach(...)
+```
+
+- `registry`：导出的原始 Map，和 `import { storeRegistry }` 拿到的是同一个引用
+- `stores`：getter，每次读取重建对象视图；销毁的 store 自动消失
+
+**说明**：
+
+- `__VUE_PAGE_STORE__` 是 dev-only 调试接口，shape 和键名可能在后续版本变化，**不要在生产代码里依赖**
+- 微前端场景下，多个子应用都加载 vue-page-store 时，最后挂载的会覆盖前面的。如需共存，请退回手动挂载并用自己的命名
+
 ## 从 v0.3.x 升级
 
 ### Breaking Changes
@@ -536,11 +695,23 @@ v0.4.0 中：
 - `$setInterval()`：页面级 interval 托管
 - `$loading.xxx`：返回 Promise 的 action 自动追踪 loading
 - `$vm`：只读逃生口，可在 init / enter 中访问 `$route / $router`
+- `registerPlugin()`：外部扩展机制（v0.5）
+
+## 从 v0.4.x 升级到 v0.5
+
+v0.5 **完全向后兼容** v0.4.x：
+
+- 所有 v0.4 的 API 行为不变
+- 新增 `registerPlugin()` 导出，不注册 plugin 等同于 v0.4 行为
+- options 现在允许包含插件声明的额外字段（如 `tasks`、`persist`）
+- dev 环境自动挂 `window.__VUE_PAGE_STORE__`，方便控制台调试
+
+升级只需要改版本号，无需改代码。
 
 ## Roadmap
 
 - **Keyed instance** — `useStore(vm, scopeKey)` 支持同定义多实例
-- **Page cache strategy** — TTL、revalidate、stale-while-enter
+- **Official plugins** — 随着 `vue-page-runtime` 等生态库成熟，补充第一方 plugin 文档
 - **More page runtime helpers** — 在不增加心智负担的前提下继续补页面层能力
 
 ## License

package/dist/index.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * vue-page-store v0.4.1
+ * vue-page-store v0.5.0
  * (c) 2026 weijianjun
  * @license MIT
  */
@@ -7,16 +7,18 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var Vue = require('vue');
+
 /*!
- * vue-page-store v0.4.1
+ * vue-page-store v0.5.0
  * (c) 2026 weijianjun
  * @license MIT
  */
 /**
- * vue-page-store 0.4.1 — Vue 2.6 Page Scope Runtime
+ * vue-page-store 0.5.0 — Vue 2.6 Page Scope Runtime
  *
  * 页面级作用域运行时容器：
- * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus
+ * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus · plugin
  *
  * v0.4 新增：
  *   source     → 页面输入 / 原始返回，和业务 state 分开
@@ -27,12 +29,13 @@ Object.defineProperty(exports, '__esModule', { value: true });
  * v0.4.1 新增：
  *   init       → store 创建后一次性初始化钩子，$vm 已可用
  *
+ * v0.5 新增：
+ *   plugin     → registerPlugin 注册外部扩展，声明字段 + 生命周期钩子
+ *
  * @author weijianjun
  * @license MIT
  */
 
-// Store 注册表（导出供调试 / devtools 使用）
-var storeRegistry = new Map();
 
 // ====== dev-only warning ======
 var isDev = typeof process !== 'undefined'
@@ -45,6 +48,47 @@ function warn(msg) {
   }
 }
 
+// Store 注册表（导出供调试 / devtools 使用）
+var storeRegistry = new Map();
+
+// v0.5 新增：dev 环境自动挂到 window，方便控制台调试
+if (isDev && typeof window !== 'undefined') {
+  window.__VUE_PAGE_STORE__ = {
+    registry: storeRegistry,
+    get stores() {
+      var result = {};
+      storeRegistry.forEach(function (s, id) { result[id] = s; });
+      return result;
+    },
+  };
+}
+
+// ====== v0.5 新增：plugin 机制 ======
+var _plugins = [];
+
+/**
+ * 注册全局 plugin
+ *
+ * plugin.name 同时作为 options 字段匹配键：
+ *   当 definePageStore options 中存在 options[plugin.name] 时，
+ *   page-store 会调用 plugin.install(store, fieldValue, { Vue })
+ *
+ * install 可返回 { enter, leave, destroy } 生命周期钩子
+ */
+function registerPlugin(plugin) {
+  if (!plugin || typeof plugin.name !== 'string') {
+    throw new Error('[vue-page-store] plugin 需要一个 name 属性');
+  }
+  if (typeof plugin.install !== 'function') {
+    throw new Error('[vue-page-store] plugin "' + plugin.name + '" 需要一个 install 方法');
+  }
+  if (_plugins.some(function (p) { return p.name === plugin.name; })) {
+    warn('plugin "' + plugin.name + '" 已注册，跳过重复注册');
+    return;
+  }
+  _plugins.push(plugin);
+}
+
 function createStoreInstance(Vue, id, options) {
   var initialState = options.state();
 
@@ -58,6 +102,9 @@ function createStoreInstance(Vue, id, options) {
   var enterHook = typeof options.enter === 'function' ? options.enter : null;
   var leaveHook = typeof options.leave === 'function' ? options.leave : null;
 
+  // ====== v0.5 新增：plugin hooks 闭包存储（由 install 填充） ======
+  var _pluginHooks = [];
+
   // --- 用一个隐藏的 Vue 实例承载响应式 state + source + loading + computed getters ---
   var computedDefs = {};
   var store = { $disposed: false };
@@ -325,6 +372,8 @@ function createStoreInstance(Vue, id, options) {
       enterHook.call(store);
     }
     store.$emit('page:enter');
+    // v0.5: plugin enter hooks
+    _pluginHooks.forEach(function (h) { if (h.enter) h.enter(); });
   }
 
   function runLeave() {
@@ -337,6 +386,8 @@ function createStoreInstance(Vue, id, options) {
       leaveHook.call(store);
     }
     store.$emit('page:leave');
+    // v0.5: plugin leave hooks
+    _pluginHooks.forEach(function (h) { if (h.leave) h.leave(); });
   }
 
   // ====== bindTo 去重标记 ======
@@ -403,6 +454,7 @@ function createStoreInstance(Vue, id, options) {
    * 销毁 store
    *
    * v0.4 变更：兜底清理 interval
+   * v0.5 变更：调用 plugin destroy 钩子
    */
   store.$destroy = function () {
     if (store.$disposed) return;
@@ -413,6 +465,9 @@ function createStoreInstance(Vue, id, options) {
     // 兜底清理 interval（正常流程 leave 已经清过，这里防遗漏）
     clearAllIntervals();
 
+    // v0.5: plugin destroy hooks
+    _pluginHooks.forEach(function (h) { if (h.destroy) h.destroy(); });
+
     store.$disposed = true;
     Object.keys(_listeners).forEach(function (key) { delete _listeners[key]; });
     vm.$destroy();
@@ -421,6 +476,15 @@ function createStoreInstance(Vue, id, options) {
 
   store._vm = vm;
 
+  // ====== v0.5 新增：plugin 安装 ======
+  // 放在最后，此时 store 的 state/getters/actions/$源数据/$setInterval 等全部就绪
+  _plugins.forEach(function (plugin) {
+    var fieldValue = options[plugin.name];
+    if (fieldValue === undefined) return;
+    var hooks = plugin.install(store, fieldValue, { Vue: Vue });
+    if (hooks) _pluginHooks.push(hooks);
+  });
+
   return store;
 }
 
@@ -433,6 +497,8 @@ function createStoreInstance(Vue, id, options) {
  *   - actions 中的 async 函数自动追踪 $loading
  * v0.4.1 变更：
  *   - options 新增 init（bindTo 之后一次性调用）
+ * v0.5 变更：
+ *   - options 中注册过的 plugin.name 字段会被交给对应 plugin 处理
  */
 function definePageStore(id, options) {
   // 入参校验
@@ -443,7 +509,7 @@ function definePageStore(id, options) {
     throw new Error('[vue-page-store] definePageStore("' + id + '") 需要 state 为函数');
   }
 
-  var _Vue = null;
+  var _Vue = Vue;
 
   return function useStore(componentVm) {
     if (storeRegistry.has(id)) {
@@ -452,17 +518,6 @@ function definePageStore(id, options) {
       return existing;
     }
 
-    if (!_Vue) {
-      try {
-        _Vue = require('vue');
-        if (_Vue.default) _Vue = _Vue.default;
-      } catch (e) {
-        throw new Error(
-          '[vue-page-store] 无法自动获取 Vue，请确保 vue 已安装'
-        );
-      }
-    }
-
     var store = createStoreInstance(_Vue, id, options);
     storeRegistry.set(id, store);
     if (componentVm) store.bindTo(componentVm);
@@ -476,8 +531,13 @@ function definePageStore(id, options) {
   };
 }
 
-var index = { definePageStore: definePageStore, storeRegistry: storeRegistry };
+var index = {
+  definePageStore: definePageStore,
+  registerPlugin: registerPlugin,
+  storeRegistry: storeRegistry
+};
 
 exports.default = index;
 exports.definePageStore = definePageStore;
+exports.registerPlugin = registerPlugin;
 exports.storeRegistry = storeRegistry;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * vue-page-store v0.4.1 - TypeScript 类型定义
+ * vue-page-store v0.5.0 - TypeScript 类型定义
  *
  * Page Scope Runtime for Vue 2.6
  */
@@ -68,6 +68,9 @@ export interface StoreOptions<
    * interval 在 leave 前已自动清理
    */
   leave?: (this: PageStore<S, Src>) => void;
+
+  /** 允许 plugin 声明的额外字段（v0.5 新增） */
+  [key: string]: any;
 }
 
 export interface Store<
@@ -138,6 +141,8 @@ export type PageStore<
  *   - async action 自动追踪 $loading
  * v0.4.1 变更：
  *   - options 新增 init（bindTo 之后一次性调用）
+ * v0.5 变更：
+ *   - options 支持 plugin 声明的自定义字段
  */
 export declare function definePageStore<
   S extends Record<string, any>,
@@ -148,4 +153,44 @@ export declare function definePageStore<
 ): (componentVm?: Vue2ComponentInstance) => PageStore<S, Src>;
 
 /** Store 注册表 */
-export declare const storeRegistry: Map<string, PageStore<any, any>>;
+export declare const storeRegistry: Map<string, PageStore<any, any>>;
+
+// ====== v0.5 新增：plugin 类型 ======
+
+/**
+ * Plugin install 返回的生命周期钩子（v0.5 新增）
+ * page-store 会在对应时机调用
+ */
+export interface PluginHooks {
+  /** 每次 page enter 之后调用（用户 enter hook + page:enter event 之后） */
+  enter?: () => void;
+  /** 每次 page leave 之后调用（用户 leave hook + page:leave event 之后） */
+  leave?: () => void;
+  /** store $destroy 时调用，用于释放 plugin 自己的资源 */
+  destroy?: () => void;
+}
+
+/**
+ * Plugin 定义（v0.5 新增）
+ *
+ * plugin.name 同时作为字段名：
+ *   当 definePageStore options 中存在 options[name] 时，
+ *   page-store 会调用 install(store, fieldValue, { Vue })
+ *
+ * install 在 store 创建末尾、bindTo 之前执行，此时 state/getters/actions/$source/$setInterval 已就绪
+ */
+export interface PageStorePlugin {
+  name: string;
+  install(
+    store: PageStore<any, any>,
+    fieldValue: any,
+    context: { Vue: any }
+  ): PluginHooks | void;
+}
+
+/**
+ * 注册全局 plugin（v0.5 新增）
+ *
+ * 同名 plugin 重复注册会被跳过并打印 warning
+ */
+export declare function registerPlugin(plugin: PageStorePlugin): void;

package/dist/index.esm.js

@@ -1,18 +1,20 @@
 /*!
- * vue-page-store v0.4.1
+ * vue-page-store v0.5.0
  * (c) 2026 weijianjun
  * @license MIT
  */
+import Vue from 'vue';
+
 /*!
- * vue-page-store v0.4.1
+ * vue-page-store v0.5.0
  * (c) 2026 weijianjun
  * @license MIT
  */
 /**
- * vue-page-store 0.4.1 — Vue 2.6 Page Scope Runtime
+ * vue-page-store 0.5.0 — Vue 2.6 Page Scope Runtime
  *
  * 页面级作用域运行时容器：
- * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus
+ * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus · plugin
  *
  * v0.4 新增：
  *   source     → 页面输入 / 原始返回，和业务 state 分开
@@ -23,12 +25,13 @@
  * v0.4.1 新增：
  *   init       → store 创建后一次性初始化钩子，$vm 已可用
  *
+ * v0.5 新增：
+ *   plugin     → registerPlugin 注册外部扩展，声明字段 + 生命周期钩子
+ *
  * @author weijianjun
  * @license MIT
  */
 
-// Store 注册表（导出供调试 / devtools 使用）
-var storeRegistry = new Map();
 
 // ====== dev-only warning ======
 var isDev = typeof process !== 'undefined'
@@ -41,6 +44,47 @@ function warn(msg) {
   }
 }
 
+// Store 注册表（导出供调试 / devtools 使用）
+var storeRegistry = new Map();
+
+// v0.5 新增：dev 环境自动挂到 window，方便控制台调试
+if (isDev && typeof window !== 'undefined') {
+  window.__VUE_PAGE_STORE__ = {
+    registry: storeRegistry,
+    get stores() {
+      var result = {};
+      storeRegistry.forEach(function (s, id) { result[id] = s; });
+      return result;
+    },
+  };
+}
+
+// ====== v0.5 新增：plugin 机制 ======
+var _plugins = [];
+
+/**
+ * 注册全局 plugin
+ *
+ * plugin.name 同时作为 options 字段匹配键：
+ *   当 definePageStore options 中存在 options[plugin.name] 时，
+ *   page-store 会调用 plugin.install(store, fieldValue, { Vue })
+ *
+ * install 可返回 { enter, leave, destroy } 生命周期钩子
+ */
+function registerPlugin(plugin) {
+  if (!plugin || typeof plugin.name !== 'string') {
+    throw new Error('[vue-page-store] plugin 需要一个 name 属性');
+  }
+  if (typeof plugin.install !== 'function') {
+    throw new Error('[vue-page-store] plugin "' + plugin.name + '" 需要一个 install 方法');
+  }
+  if (_plugins.some(function (p) { return p.name === plugin.name; })) {
+    warn('plugin "' + plugin.name + '" 已注册，跳过重复注册');
+    return;
+  }
+  _plugins.push(plugin);
+}
+
 function createStoreInstance(Vue, id, options) {
   var initialState = options.state();
 
@@ -54,6 +98,9 @@ function createStoreInstance(Vue, id, options) {
   var enterHook = typeof options.enter === 'function' ? options.enter : null;
   var leaveHook = typeof options.leave === 'function' ? options.leave : null;
 
+  // ====== v0.5 新增：plugin hooks 闭包存储（由 install 填充） ======
+  var _pluginHooks = [];
+
   // --- 用一个隐藏的 Vue 实例承载响应式 state + source + loading + computed getters ---
   var computedDefs = {};
   var store = { $disposed: false };
@@ -321,6 +368,8 @@ function createStoreInstance(Vue, id, options) {
       enterHook.call(store);
     }
     store.$emit('page:enter');
+    // v0.5: plugin enter hooks
+    _pluginHooks.forEach(function (h) { if (h.enter) h.enter(); });
   }
 
   function runLeave() {
@@ -333,6 +382,8 @@ function createStoreInstance(Vue, id, options) {
       leaveHook.call(store);
     }
     store.$emit('page:leave');
+    // v0.5: plugin leave hooks
+    _pluginHooks.forEach(function (h) { if (h.leave) h.leave(); });
   }
 
   // ====== bindTo 去重标记 ======
@@ -399,6 +450,7 @@ function createStoreInstance(Vue, id, options) {
    * 销毁 store
    *
    * v0.4 变更：兜底清理 interval
+   * v0.5 变更：调用 plugin destroy 钩子
    */
   store.$destroy = function () {
     if (store.$disposed) return;
@@ -409,6 +461,9 @@ function createStoreInstance(Vue, id, options) {
     // 兜底清理 interval（正常流程 leave 已经清过，这里防遗漏）
     clearAllIntervals();
 
+    // v0.5: plugin destroy hooks
+    _pluginHooks.forEach(function (h) { if (h.destroy) h.destroy(); });
+
     store.$disposed = true;
     Object.keys(_listeners).forEach(function (key) { delete _listeners[key]; });
     vm.$destroy();
@@ -417,6 +472,15 @@ function createStoreInstance(Vue, id, options) {
 
   store._vm = vm;
 
+  // ====== v0.5 新增：plugin 安装 ======
+  // 放在最后，此时 store 的 state/getters/actions/$源数据/$setInterval 等全部就绪
+  _plugins.forEach(function (plugin) {
+    var fieldValue = options[plugin.name];
+    if (fieldValue === undefined) return;
+    var hooks = plugin.install(store, fieldValue, { Vue: Vue });
+    if (hooks) _pluginHooks.push(hooks);
+  });
+
   return store;
 }
 
@@ -429,6 +493,8 @@ function createStoreInstance(Vue, id, options) {
  *   - actions 中的 async 函数自动追踪 $loading
  * v0.4.1 变更：
  *   - options 新增 init（bindTo 之后一次性调用）
+ * v0.5 变更：
+ *   - options 中注册过的 plugin.name 字段会被交给对应 plugin 处理
  */
 function definePageStore(id, options) {
   // 入参校验
@@ -439,7 +505,7 @@ function definePageStore(id, options) {
     throw new Error('[vue-page-store] definePageStore("' + id + '") 需要 state 为函数');
   }
 
-  var _Vue = null;
+  var _Vue = Vue;
 
   return function useStore(componentVm) {
     if (storeRegistry.has(id)) {
@@ -448,17 +514,6 @@ function definePageStore(id, options) {
       return existing;
     }
 
-    if (!_Vue) {
-      try {
-        _Vue = require('vue');
-        if (_Vue.default) _Vue = _Vue.default;
-      } catch (e) {
-        throw new Error(
-          '[vue-page-store] 无法自动获取 Vue，请确保 vue 已安装'
-        );
-      }
-    }
-
     var store = createStoreInstance(_Vue, id, options);
     storeRegistry.set(id, store);
     if (componentVm) store.bindTo(componentVm);
@@ -472,6 +527,10 @@ function definePageStore(id, options) {
   };
 }
 
-var index = { definePageStore: definePageStore, storeRegistry: storeRegistry };
+var index = {
+  definePageStore: definePageStore,
+  registerPlugin: registerPlugin,
+  storeRegistry: storeRegistry
+};
 
-export { index as default, definePageStore, storeRegistry };
+export { index as default, definePageStore, registerPlugin, storeRegistry };

package/dist/index.umd.js

@@ -1,24 +1,24 @@
 /*!
- * vue-page-store v0.4.1
+ * vue-page-store v0.5.0
  * (c) 2026 weijianjun
  * @license MIT
  */
 (function (global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
-  typeof define === 'function' && define.amd ? define(['exports'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.VuePageStore = {}));
-})(this, (function (exports) { 'use strict';
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('vue')) :
+  typeof define === 'function' && define.amd ? define(['exports', 'vue'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.VuePageStore = {}, global.Vue));
+})(this, (function (exports, Vue) { 'use strict';
 
   /*!
-   * vue-page-store v0.4.1
+   * vue-page-store v0.5.0
    * (c) 2026 weijianjun
    * @license MIT
    */
   /**
-   * vue-page-store 0.4.1 — Vue 2.6 Page Scope Runtime
+   * vue-page-store 0.5.0 — Vue 2.6 Page Scope Runtime
    *
    * 页面级作用域运行时容器：
-   * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus
+   * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus · plugin
    *
    * v0.4 新增：
    *   source     → 页面输入 / 原始返回，和业务 state 分开
@@ -29,12 +29,13 @@
    * v0.4.1 新增：
    *   init       → store 创建后一次性初始化钩子，$vm 已可用
    *
+   * v0.5 新增：
+   *   plugin     → registerPlugin 注册外部扩展，声明字段 + 生命周期钩子
+   *
    * @author weijianjun
    * @license MIT
    */
 
-  // Store 注册表（导出供调试 / devtools 使用）
-  var storeRegistry = new Map();
 
   // ====== dev-only warning ======
   var isDev = typeof process !== 'undefined'
@@ -47,6 +48,47 @@
     }
   }
 
+  // Store 注册表（导出供调试 / devtools 使用）
+  var storeRegistry = new Map();
+
+  // v0.5 新增：dev 环境自动挂到 window，方便控制台调试
+  if (isDev && typeof window !== 'undefined') {
+    window.__VUE_PAGE_STORE__ = {
+      registry: storeRegistry,
+      get stores() {
+        var result = {};
+        storeRegistry.forEach(function (s, id) { result[id] = s; });
+        return result;
+      },
+    };
+  }
+
+  // ====== v0.5 新增：plugin 机制 ======
+  var _plugins = [];
+
+  /**
+   * 注册全局 plugin
+   *
+   * plugin.name 同时作为 options 字段匹配键：
+   *   当 definePageStore options 中存在 options[plugin.name] 时，
+   *   page-store 会调用 plugin.install(store, fieldValue, { Vue })
+   *
+   * install 可返回 { enter, leave, destroy } 生命周期钩子
+   */
+  function registerPlugin(plugin) {
+    if (!plugin || typeof plugin.name !== 'string') {
+      throw new Error('[vue-page-store] plugin 需要一个 name 属性');
+    }
+    if (typeof plugin.install !== 'function') {
+      throw new Error('[vue-page-store] plugin "' + plugin.name + '" 需要一个 install 方法');
+    }
+    if (_plugins.some(function (p) { return p.name === plugin.name; })) {
+      warn('plugin "' + plugin.name + '" 已注册，跳过重复注册');
+      return;
+    }
+    _plugins.push(plugin);
+  }
+
   function createStoreInstance(Vue, id, options) {
     var initialState = options.state();
 
@@ -60,6 +102,9 @@
     var enterHook = typeof options.enter === 'function' ? options.enter : null;
     var leaveHook = typeof options.leave === 'function' ? options.leave : null;
 
+    // ====== v0.5 新增：plugin hooks 闭包存储（由 install 填充） ======
+    var _pluginHooks = [];
+
     // --- 用一个隐藏的 Vue 实例承载响应式 state + source + loading + computed getters ---
     var computedDefs = {};
     var store = { $disposed: false };
@@ -327,6 +372,8 @@
         enterHook.call(store);
       }
       store.$emit('page:enter');
+      // v0.5: plugin enter hooks
+      _pluginHooks.forEach(function (h) { if (h.enter) h.enter(); });
     }
 
     function runLeave() {
@@ -339,6 +386,8 @@
         leaveHook.call(store);
       }
       store.$emit('page:leave');
+      // v0.5: plugin leave hooks
+      _pluginHooks.forEach(function (h) { if (h.leave) h.leave(); });
     }
 
     // ====== bindTo 去重标记 ======
@@ -405,6 +454,7 @@
      * 销毁 store
      *
      * v0.4 变更：兜底清理 interval
+     * v0.5 变更：调用 plugin destroy 钩子
      */
     store.$destroy = function () {
       if (store.$disposed) return;
@@ -415,6 +465,9 @@
       // 兜底清理 interval（正常流程 leave 已经清过，这里防遗漏）
       clearAllIntervals();
 
+      // v0.5: plugin destroy hooks
+      _pluginHooks.forEach(function (h) { if (h.destroy) h.destroy(); });
+
       store.$disposed = true;
       Object.keys(_listeners).forEach(function (key) { delete _listeners[key]; });
       vm.$destroy();
@@ -423,6 +476,15 @@
 
     store._vm = vm;
 
+    // ====== v0.5 新增：plugin 安装 ======
+    // 放在最后，此时 store 的 state/getters/actions/$源数据/$setInterval 等全部就绪
+    _plugins.forEach(function (plugin) {
+      var fieldValue = options[plugin.name];
+      if (fieldValue === undefined) return;
+      var hooks = plugin.install(store, fieldValue, { Vue: Vue });
+      if (hooks) _pluginHooks.push(hooks);
+    });
+
     return store;
   }
 
@@ -435,6 +497,8 @@
    *   - actions 中的 async 函数自动追踪 $loading
    * v0.4.1 变更：
    *   - options 新增 init（bindTo 之后一次性调用）
+   * v0.5 变更：
+   *   - options 中注册过的 plugin.name 字段会被交给对应 plugin 处理
    */
   function definePageStore(id, options) {
     // 入参校验
@@ -445,7 +509,7 @@
       throw new Error('[vue-page-store] definePageStore("' + id + '") 需要 state 为函数');
     }
 
-    var _Vue = null;
+    var _Vue = Vue;
 
     return function useStore(componentVm) {
       if (storeRegistry.has(id)) {
@@ -454,17 +518,6 @@
         return existing;
       }
 
-      if (!_Vue) {
-        try {
-          _Vue = require('vue');
-          if (_Vue.default) _Vue = _Vue.default;
-        } catch (e) {
-          throw new Error(
-            '[vue-page-store] 无法自动获取 Vue，请确保 vue 已安装'
-          );
-        }
-      }
-
       var store = createStoreInstance(_Vue, id, options);
       storeRegistry.set(id, store);
       if (componentVm) store.bindTo(componentVm);
@@ -478,10 +531,15 @@
     };
   }
 
-  var index = { definePageStore: definePageStore, storeRegistry: storeRegistry };
+  var index = {
+    definePageStore: definePageStore,
+    registerPlugin: registerPlugin,
+    storeRegistry: storeRegistry
+  };
 
   exports.default = index;
   exports.definePageStore = definePageStore;
+  exports.registerPlugin = registerPlugin;
   exports.storeRegistry = storeRegistry;
 
   Object.defineProperty(exports, '__esModule', { value: true });

package/dist/index.umd.min.js

@@ -1,19 +1,19 @@
 /*!
- * vue-page-store v0.4.1
+ * vue-page-store v0.5.0
  * (c) 2026 weijianjun
  * @license MIT
  */
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).VuePageStore={})}(this,function(e){"use strict";
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("vue")):"function"==typeof define&&define.amd?define(["exports","vue"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).VuePageStore={},e.Vue)}(this,function(e,t){"use strict";
 /*!
-   * vue-page-store v0.4.1
+   * vue-page-store v0.5.0
    * (c) 2026 weijianjun
    * @license MIT
    */
 /**
-   * vue-page-store 0.4.1 — Vue 2.6 Page Scope Runtime
+   * vue-page-store 0.5.0 — Vue 2.6 Page Scope Runtime
    *
    * 页面级作用域运行时容器：
-   * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus
+   * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus · plugin
    *
    * v0.4 新增：
    *   source     → 页面输入 / 原始返回，和业务 state 分开
@@ -24,6 +24,9 @@
    * v0.4.1 新增：
    *   init       → store 创建后一次性初始化钩子，$vm 已可用
    *
+   * v0.5 新增：
+   *   plugin     → registerPlugin 注册外部扩展，声明字段 + 生命周期钩子
+   *
    * @author weijianjun
    * @license MIT
-   */var t=new Map,n="undefined"!=typeof process&&process.env&&"production"!==process.env.NODE_ENV;function o(e){n&&console.warn("[vue-page-store] "+e)}function r(e,n,r){var i=r.state(),c="function"==typeof r.source?r.source():{},u=r.getters||{},f=r.actions||{},a="function"==typeof r.enter?r.enter:null,s="function"==typeof r.leave?r.leave:null,d={},l={$disposed:!1};Object.keys(u).forEach(function(e){d[e]=function(){return u[e].call(l)}});var p=new e({data:function(){return{$$state:i,$$source:c,$$loading:{},$$status:{mounted:!1,active:!1}}},computed:d}),v=p.$data.$$state,$=p.$data.$$source,h=p.$data.$$loading,y=p.$data.$$status;Object.keys(i).forEach(function(e){Object.defineProperty(l,e,{enumerable:!0,configurable:!0,get:function(){return v[e]},set:function(t){l.$disposed?o('store "'+n+'" 已销毁，忽略对 "'+e+'" 的写入'):v[e]=t}})}),l.$source=$,l.$loading=h,Object.keys(u).forEach(function(e){Object.defineProperty(l,e,{enumerable:!0,get:function(){return p[e]}})});var b={};function g(t){b[t]--,b[t]<=0&&(b[t]=0,e.set(h,t,!1))}Object.keys(f).forEach(function(t){var n=f[t].bind(l);l[t]=function(){var o=n.apply(null,arguments);o&&"function"==typeof o.then&&(b[t]||(b[t]=0),b[t]++,e.set(h,t,!0),Promise.resolve(o).then(function(){g(t)},function(){g(t)}));return o}});var m=r.watch||{};Object.entries(m).forEach(function(e){var t,r,i=e[0],c=e[1];if("function"==typeof c)t=c,r={};else if(t=c.handler,r={},c.deep&&(r.deep=!0),c.immediate&&(r.immediate=!0),!t)return void o('watch "'+i+'" in store "'+n+'" 缺少 handler，该 watcher 将被跳过');p.$watch(function(){return i.split(".").reduce(function(e,t){return e&&e[t]},l)},t.bind(l),r)}),l.$state=v,l.$status=y,l.$id=n;var O=null;Object.defineProperty(l,"$vm",{enumerable:!0,configurable:!1,get:function(){return O},set:function(){o("$vm 是只读属性，不允许业务侧重写")}}),l.$patch=function(t){if(l.$disposed)o('store "'+n+'" 已销毁，忽略 $patch 操作');else{var r="function"==typeof t?t(v):t;Object.keys(r).forEach(function(t){e.set(v,t,r[t])})}},l.$reset=function(){var t=r.state();Object.keys(t).forEach(function(n){e.set(v,n,t[n])}),Object.keys(v).forEach(function(n){n in t||e.delete(v,n)});var n="function"==typeof r.source?r.source():{};Object.keys(n).forEach(function(t){e.set($,t,n[t])}),Object.keys($).forEach(function(t){t in n||e.delete($,t)})};var E={};l.$emit=function(e,t){var n=E[e];n&&n.slice().forEach(function(e){e(t)})},l.$on=function(e,t){return E[e]||(E[e]=[]),E[e].push(t),function(){if(E[e]){var n=E[e].indexOf(t);n>-1&&E[e].splice(n,1)}}},l.$off=function(e,t){if(E[e])if(t){var n=E[e].indexOf(t);n>-1&&E[e].splice(n,1)}else delete E[e]};var j=[];function k(){j.forEach(function(e){e.stopped||(clearInterval(e.id),e.stopped=!0)}),j.length=0}l.$setInterval=function(e,t){var n={id:setInterval(e,t),stopped:!1};j.push(n);return function(){if(!n.stopped){clearInterval(n.id),n.stopped=!0;var e=j.indexOf(n);e>-1&&j.splice(e,1)}}};var w=!1;function P(){w||(w=!0,y.mounted=!0,y.active=!0,a&&a.call(l),l.$emit("page:enter"))}function S(){w&&(k(),w=!1,y.active=!1,s&&s.call(l),l.$emit("page:leave"))}var x="undefined"!=typeof WeakSet?new WeakSet:null,_=x?null:[];return l.bindTo=function(e){return l.$disposed||function(e){return x?x.has(e):_.indexOf(e)>-1}(e)||(function(e){x?x.add(e):_.push(e)}(e),O=e,(e._provided||(e._provided={})).pageStore=l,e.$on("hook:mounted",function(){P()}),e.$on("hook:activated",function(){P()}),e.$on("hook:deactivated",function(){S()}),e.$on("hook:beforeDestroy",function(){S(),l.$destroy()})),l},l.$destroy=function(){l.$disposed||(y.mounted=!1,y.active=!1,k(),l.$disposed=!0,Object.keys(E).forEach(function(e){delete E[e]}),p.$destroy(),t.delete(n))},l._vm=p,l}function i(e,n){if(!e||"string"!=typeof e)throw new Error("[vue-page-store] definePageStore 需要一个非空字符串作为 id");if(!n||"function"!=typeof n.state)throw new Error('[vue-page-store] definePageStore("'+e+'") 需要 state 为函数');var o=null;return function(i){if(t.has(e)){var c=t.get(e);return i&&c.bindTo(i),c}if(!o)try{(o=require("vue")).default&&(o=o.default)}catch(e){throw new Error("[vue-page-store] 无法自动获取 Vue，请确保 vue 已安装")}var u=r(o,e,n);return t.set(e,u),i&&u.bindTo(i),"function"==typeof n.init&&n.init.call(u),u}}var c={definePageStore:i,storeRegistry:t};e.default=c,e.definePageStore=i,e.storeRegistry=t,Object.defineProperty(e,"__esModule",{value:!0})});
+   */var n="undefined"!=typeof process&&process.env&&"production"!==process.env.NODE_ENV;function o(e){n&&console.warn("[vue-page-store] "+e)}var r=new Map;n&&"undefined"!=typeof window&&(window.__VUE_PAGE_STORE__={registry:r,get stores(){var e={};return r.forEach(function(t,n){e[n]=t}),e}});var i=[];function u(e){if(!e||"string"!=typeof e.name)throw new Error("[vue-page-store] plugin 需要一个 name 属性");if("function"!=typeof e.install)throw new Error('[vue-page-store] plugin "'+e.name+'" 需要一个 install 方法');i.some(function(t){return t.name===e.name})?o('plugin "'+e.name+'" 已注册，跳过重复注册'):i.push(e)}function a(e,t,n){var u=n.state(),a="function"==typeof n.source?n.source():{},f=n.getters||{},c=n.actions||{},s="function"==typeof n.enter?n.enter:null,d="function"==typeof n.leave?n.leave:null,l=[],p={},v={$disposed:!1};Object.keys(f).forEach(function(e){p[e]=function(){return f[e].call(v)}});var $=new e({data:function(){return{$$state:u,$$source:a,$$loading:{},$$status:{mounted:!1,active:!1}}},computed:p}),h=$.$data.$$state,y=$.$data.$$source,g=$.$data.$$loading,b=$.$data.$$status;Object.keys(u).forEach(function(e){Object.defineProperty(v,e,{enumerable:!0,configurable:!0,get:function(){return h[e]},set:function(n){v.$disposed?o('store "'+t+'" 已销毁，忽略对 "'+e+'" 的写入'):h[e]=n}})}),v.$source=y,v.$loading=g,Object.keys(f).forEach(function(e){Object.defineProperty(v,e,{enumerable:!0,get:function(){return $[e]}})});var m={};function E(t){m[t]--,m[t]<=0&&(m[t]=0,e.set(g,t,!1))}Object.keys(c).forEach(function(t){var n=c[t].bind(v);v[t]=function(){var o=n.apply(null,arguments);o&&"function"==typeof o.then&&(m[t]||(m[t]=0),m[t]++,e.set(g,t,!0),Promise.resolve(o).then(function(){E(t)},function(){E(t)}));return o}});var O=n.watch||{};Object.entries(O).forEach(function(e){var n,r,i=e[0],u=e[1];if("function"==typeof u)n=u,r={};else if(n=u.handler,r={},u.deep&&(r.deep=!0),u.immediate&&(r.immediate=!0),!n)return void o('watch "'+i+'" in store "'+t+'" 缺少 handler，该 watcher 将被跳过');$.$watch(function(){return i.split(".").reduce(function(e,t){return e&&e[t]},v)},n.bind(v),r)}),v.$state=h,v.$status=b,v.$id=t;var w=null;Object.defineProperty(v,"$vm",{enumerable:!0,configurable:!1,get:function(){return w},set:function(){o("$vm 是只读属性，不允许业务侧重写")}}),v.$patch=function(n){if(v.$disposed)o('store "'+t+'" 已销毁，忽略 $patch 操作');else{var r="function"==typeof n?n(h):n;Object.keys(r).forEach(function(t){e.set(h,t,r[t])})}},v.$reset=function(){var t=n.state();Object.keys(t).forEach(function(n){e.set(h,n,t[n])}),Object.keys(h).forEach(function(n){n in t||e.delete(h,n)});var o="function"==typeof n.source?n.source():{};Object.keys(o).forEach(function(t){e.set(y,t,o[t])}),Object.keys(y).forEach(function(t){t in o||e.delete(y,t)})};var j={};v.$emit=function(e,t){var n=j[e];n&&n.slice().forEach(function(e){e(t)})},v.$on=function(e,t){return j[e]||(j[e]=[]),j[e].push(t),function(){if(j[e]){var n=j[e].indexOf(t);n>-1&&j[e].splice(n,1)}}},v.$off=function(e,t){if(j[e])if(t){var n=j[e].indexOf(t);n>-1&&j[e].splice(n,1)}else delete j[e]};var k=[];function P(){k.forEach(function(e){e.stopped||(clearInterval(e.id),e.stopped=!0)}),k.length=0}v.$setInterval=function(e,t){var n={id:setInterval(e,t),stopped:!1};k.push(n);return function(){if(!n.stopped){clearInterval(n.id),n.stopped=!0;var e=k.indexOf(n);e>-1&&k.splice(e,1)}}};var _=!1;function S(){_||(_=!0,b.mounted=!0,b.active=!0,s&&s.call(v),v.$emit("page:enter"),l.forEach(function(e){e.enter&&e.enter()}))}function x(){_&&(P(),_=!1,b.active=!1,d&&d.call(v),v.$emit("page:leave"),l.forEach(function(e){e.leave&&e.leave()}))}var T="undefined"!=typeof WeakSet?new WeakSet:null,V=T?null:[];return v.bindTo=function(e){return v.$disposed||function(e){return T?T.has(e):V.indexOf(e)>-1}(e)||(function(e){T?T.add(e):V.push(e)}(e),w=e,(e._provided||(e._provided={})).pageStore=v,e.$on("hook:mounted",function(){S()}),e.$on("hook:activated",function(){S()}),e.$on("hook:deactivated",function(){x()}),e.$on("hook:beforeDestroy",function(){x(),v.$destroy()})),v},v.$destroy=function(){v.$disposed||(b.mounted=!1,b.active=!1,P(),l.forEach(function(e){e.destroy&&e.destroy()}),v.$disposed=!0,Object.keys(j).forEach(function(e){delete j[e]}),$.$destroy(),r.delete(t))},v._vm=$,i.forEach(function(t){var o=n[t.name];if(void 0!==o){var r=t.install(v,o,{Vue:e});r&&l.push(r)}}),v}function f(e,n){if(!e||"string"!=typeof e)throw new Error("[vue-page-store] definePageStore 需要一个非空字符串作为 id");if(!n||"function"!=typeof n.state)throw new Error('[vue-page-store] definePageStore("'+e+'") 需要 state 为函数');var o=t;return function(t){if(r.has(e)){var i=r.get(e);return t&&i.bindTo(t),i}var u=a(o,e,n);return r.set(e,u),t&&u.bindTo(t),"function"==typeof n.init&&n.init.call(u),u}}var c={definePageStore:f,registerPlugin:u,storeRegistry:r};e.default=c,e.definePageStore=f,e.registerPlugin=u,e.storeRegistry=r,Object.defineProperty(e,"__esModule",{value:!0})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-page-store",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Vue 2.6 页面级 Store —— 状态、通信、生命周期，一个作用域全收",
   "author": "weijianjun",
   "license": "MIT",