vue-page-store 0.3.1 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # vue-page-store
 
-> Vue 2.6 页面级作用域运行时容器 —— 状态、生命周期、副作用、通信，一个作用域全收。
+> Vue 2.6 页面级作用域运行时容器 —— source、state、getters、actions、watch、init/enter/leave，一个页面作用域全收。
 
 ## 它是什么
 
@@ -8,26 +8,30 @@
 
 一个 `definePageStore` 定义一个 **Page Scope** —— 它统一管理这个页面作用域内的：
 
-- **state** — 响应式页面状态
+- **source** — 页面输入 / 原始返回（如路由参数、接口响应）
+- **state** — 响应式业务状态
 - **getters** — 派生计算
 - **actions** — 业务逻辑
 - **watch** — 声明式副作用
-- **lifecycle** — 页面生命周期（mount / unmount / activate / deactivate）
+- **init** — 一次性初始化（拉字典、注册事件监听等）
+- **enter / leave** — 页面可见性生命周期
+- **$setInterval** — 页面级定时器托管
 - **event bus** — 页面内作用域通信
 
-页面销毁时 `$destroy` 一键回收，不污染全局。
+页面离开时可以自动清理页面级定时器，页面销毁时 `$destroy` 一键回收，不污染全局。
 
 ## 它不是什么
 
-- **不是 Vuex / Pinia 替代品** — 全局状态（用户信息、权限、路由）请继续用 Vuex
+- **不是 Vuex / Pinia 替代品** — 全局状态（用户信息、权限、路由）请继续用 Vuex / Pinia
 - **不是全局状态管理方案** — 它的作用域是"页面"，不是"应用"
+- **不是大而全的框架** — 它只解决复杂页面的页面层状态编排
 
-| | Vuex | vue-page-store |
+| | Vuex / Pinia | vue-page-store |
 |---|---|---|
 | 作用域 | 全局 | 页面 |
-| 生命周期 | 跟随应用 | 跟随页面组件 |
+| 生命周期 | 跟随应用 | 跟随页面可见性 / 页面实例 |
 | 适合 | 用户信息、权限、路由状态 | 仪表盘、漏斗详情、大型配置页 |
-| 销毁 | 通常不销毁 | 页面离开即回收 |
+| 销毁 | 通常不销毁 | 页面离开 / 销毁时可回收 |
 
 ## 安装
 
@@ -42,48 +46,85 @@ npm install vue-page-store
 ### 1. 定义 store
 
 ```js
-// stores/funnel.js
+// stores/order-list.js
 import { definePageStore } from 'vue-page-store'
 
-export const useFunnelStore = definePageStore('funnelDetail', {
+export const useOrderStore = definePageStore('orderList', {
+  source: () => ({
+    response: null,
+    query: {},
+  }),
+
   state: () => ({
-    filters: {},
-    list: [],
-    loading: false
+    keyword: '',
+    page: 1,
+    pageSize: 20,
+    selectedIds: [],
+    deleteDialogVisible: false,
   }),
 
   getters: {
-    isEmpty() { return this.list.length === 0 },
-    isReady() { return !this.loading }
+    list() {
+      return this.$source.response?.list || []
+    },
+    total() {
+      return this.$source.response?.total || 0
+    },
+    hasSelection() {
+      return this.selectedIds.length > 0
+    },
+    showEmpty() {
+      return !this.$loading.search && this.list.length === 0
+    }
   },
 
   actions: {
-    async fetchData() {
-      this.loading = true
-      try {
-        this.list = await api.getFunnelData(this.filters)
-      } finally {
-        this.loading = false
-      }
+    async search() {
+      const res = await api.getOrders({
+        keyword: this.keyword,
+        page: this.page,
+        pageSize: this.pageSize,
+      })
+      this.$source.response = res
+    },
+
+    async batchDelete() {
+      await api.deleteOrders(this.selectedIds)
+      this.selectedIds = []
+      this.deleteDialogVisible = false
+      this.search()
+    },
+
+    openDeleteDialog() {
+      this.deleteDialogVisible = true
+    },
+
+    closeDeleteDialog() {
+      this.deleteDialogVisible = false
     }
   },
 
   watch: {
-    // 函数简写 — 默认浅监听
-    'filters.dateRange'(val) {
-      this.fetchData()
-    },
-    // 对象写法 — 显式 deep
-    'filters': {
-      handler(val) { this.fetchData() },
-      deep: true
+    keyword() {
+      this.page = 1
     }
   },
 
-  lifecycle: {
-    mount()    { this.fetchData() },
-    unmount()  { console.log('funnel page destroyed') },
-    activate() { this.fetchData() },
+  // 只执行一次：拉下拉框选项、注册事件监听等
+  init() {
+    this.loadDictOptions()
+    this.$on('child:refresh', () => this.search())
+  },
+
+  // 每次页面可见时执行
+  enter() {
+    this.$source.query = this.$vm.$route.query
+    this.search()
+    this.$setInterval(() => this.search(), 5000)
+  },
+
+  leave() {
+    // interval 会自动清理
   }
 })
 ```
@@ -91,13 +132,13 @@ export const useFunnelStore = definePageStore('funnelDetail', {
 ### 2. 页面组件中使用
 
 ```js
-// FunnelPage.vue
-import { useFunnelStore } from './stores/funnel'
+// OrderListPage.vue
+import { useOrderStore } from './stores/order-list'
 
 export default {
   created() {
-    // 传入 this → 自动绑定生命周期 + 自动 provide + 页面销毁时自动回收
-    this.pageStore = useFunnelStore(this)
+    // 传入 this → 自动绑定 init/enter/leave + 自动 provide + 页面销毁时自动回收
+    this.pageStore = useOrderStore(this)
   }
 }
 ```
@@ -105,16 +146,17 @@ export default {
 ### 3. 子组件中使用
 
 ```js
-// FilterPanel.vue — 不需要 import 任何 store 文件
+// FilterPanel.vue — 不需要 import store 文件
 export default {
   inject: ['pageStore'],
   mounted() {
-    this.pageStore.fetchData()  // 直接用
+    this.pageStore.search()
   }
 }
 ```
 
-所有页面统一用 `this.pageStore`，所有子组件统一 `inject: ['pageStore']`。不需要知道父页面用的哪个 store 定义，零耦合。
+所有页面统一用 `this.pageStore`，所有子组件统一 `inject: ['pageStore']`。  
+不需要知道父页面用的哪个 store 定义，零耦合。
 
 ## API
 
@@ -126,11 +168,14 @@ export default {
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
-| `state` | `() => Object` | **必填**，状态工厂函数 |
+| `state` | `() => Object` | **必填**，业务状态工厂函数 |
+| `source` | `() => Object` | 页面输入 / 原始返回工厂函数 |
 | `getters` | `{ [key]: function }` | 派生计算，`this` 指向 store |
 | `actions` | `{ [key]: function }` | 业务方法，`this` 指向 store |
 | `watch` | `{ [path]: handler \| options }` | 声明式 watcher，支持 dot-path |
-| `lifecycle` | `{ mount, unmount, activate, deactivate }` | 页面生命周期钩子 |
+| `init` | `function` | store 创建后一次性调用，`$vm` 已可用。适合拉字典、注册事件监听 |
+| `enter` | `function` | 页面进入可见 / 可交互状态时触发 |
+| `leave` | `function` | 页面离开可见 / 可交互状态时触发 |
 
 ### Store 实例属性与方法
 
@@ -138,11 +183,15 @@ export default {
 |---|---|
 | `store.xxx` | 直接访问 state 字段 |
 | `store.$state` | 原始响应式 state 对象 |
+| `store.$source` | 原始响应式 source 对象 |
+| `store.$loading` | action loading 状态对象，如 `store.$loading.search` |
 | `store.$status` | `{ mounted, active }` 响应式状态 |
 | `store.$disposed` | store 是否已销毁 |
 | `store.$id` | store 唯一标识 |
+| `store.$vm` | 绑定的页面组件实例（只读逃生口） |
 | `store.$patch(partial \| fn)` | 批量更新 state（浅合并） |
-| `store.$reset()` | 重置到 `state()` 初始值，清除动态字段 |
+| `store.$reset()` | 重置到 `state()` + `source()` 初始值，清除动态字段 |
+| `store.$setInterval(fn, delay)` | 注册页面级 interval，leave / destroy 自动清理 |
 | `store.$emit(event, payload)` | 发射事件（当前 store 作用域） |
 | `store.$on(event, handler)` | 订阅事件，返回取消函数 |
 | `store.$off(event, handler?)` | 取消订阅 |
@@ -165,19 +214,208 @@ watch: {
 }
 ```
 
-## State Shape 规则
+## source 与 state
+
+v0.4 引入了 `source`，用于把"页面输入 / 原始返回"和"业务状态"分开。
+
+### 推荐分工
+
+- **source**：路由参数、接口原始响应、页面输入上下文
+- **state**：keyword、分页、选中项、弹窗状态、表单草稿等业务状态
+
+```js
+source: () => ({
+  response: null,
+  query: {},
+}),
+
+state: () => ({
+  keyword: '',
+  page: 1,
+  selectedIds: [],
+})
+```
+
+### 为什么要分开
+
+- 原始返回不再和业务状态混在一起
+- getters 可以同时基于 `this.$source` 和 `this.xxx` 计算
+- `$reset()` 时 source / state 一起恢复，更清晰
+
+## init / enter / leave
+
+v0.4 用 `enter / leave` 替换了 v0.3 的 `lifecycle.mount / unmount / activate / deactivate`。
+
+v0.4.1 新增 `init`，用于 store 创建后的一次性初始化。
+
+### 语义
+
+- **init**：store 创建后一次性调用，`$vm` 已可用，DOM 未就绪
+- **enter**：页面进入可见 / 可交互状态
+- **leave**：页面离开可见 / 可交互状态
+
+### 执行时序
+
+```
+created() 开始
+  └→ useStore(this)
+       └→ createStoreInstance()   ← state/source/getters/actions 就绪
+       └→ bindTo(this)            ← $vm 赋值
+       └→ ★ init()               ← $vm 可用，只执行一次
+  └→ created() 剩余代码
+mounted()
+  └→ ★ enter()                   ← DOM 就绪，每次可见都执行
+
+--- keep-alive 切走 ---
+deactivated()
+  └→ clearAllIntervals()
+  └→ ★ leave()
+
+--- keep-alive 切回 ---
+activated()
+  └→ ★ enter()                   ← 重新开轮询、刷数据
+
+--- 页面销毁 ---
+beforeDestroy()
+  └→ ★ leave()（如果还没 leave）
+  └→ $destroy()
+```
+
+### 分工原则
+
+| 钩子 | 执行次数 | $vm | DOM | 典型场景 |
+|---|---|---|---|---|
+| `init` | 一次 | ✅ | ❌ | 拉下拉框选项、注册事件监听、从 localStorage 恢复配置、初始化 WebSocket |
+| `enter` | 每次可见 | ✅ | ✅ | 读路由参数、刷列表数据、开轮询 |
+| `leave` | 每次离开 | ✅ | ✅ | 通常不需要写，interval 已自动清理 |
+
+### keep-alive 行为
+
+- 首次 `mounted` → `enter`
+- `activated` → `enter`
+- `deactivated` → `leave`
+- `beforeDestroy` → 如果当前还没 leave，先 leave，再 `$destroy`
+
+### 适合放在 init 里的逻辑
+
+- 拉下拉框 / 字典选项（只需要一次）
+- 注册 `$on` 监听 store 内部事件
+- 从 localStorage 恢复上次的筛选条件
+- 初始化 WebSocket / EventSource 连接
+- 根据用户权限裁剪 columns / 按钮配置
+
+### 适合放在 enter 里的逻辑
+
+- 根据 `$route` 初始化 source / state（keep-alive 切回时路由参数可能变了）
+- 首屏加载 / 刷新列表数据
+- 启动页面轮询
+
+```js
+init() {
+  this.loadDictOptions()
+  this.$on('child:refresh', () => this.search())
+},
+
+enter() {
+  this.$source.query = this.$vm.$route.query
+  this.search()
+  this.$setInterval(() => this.search(), 5000)
+},
+
+leave() {
+  // interval 自动清理
+}
+```
+
+## `$setInterval`
+
+后台页面经常有轮询 / 倒计时需求，v0.4 提供 `$setInterval(fn, delay)` 统一托管页面级 interval。
+
+### 特性
+
+- 返回 `stop` 函数，可手动停止
+- `leave` 时自动清理所有已注册 interval
+- `$destroy()` 时兜底清理
+- `enter` 时**不会自动恢复**，需要你自己重新注册
+
+```js
+enter() {
+  this.$setInterval(() => {
+    this.search()
+  }, 5000)
+}
+```
+
+## 异步 action 与 `$loading`
+
+v0.4 对返回 Promise 的 action 自动追踪 loading 状态。
+
+你不需要额外包装器，直接写普通 async 函数即可：
+
+```js
+actions: {
+  async search() {
+    const res = await api.getOrders(...)
+    this.$source.response = res
+  }
+}
+```
+
+模板中可以直接使用：
+
+```html
+<!-- 搜索：只显示 loading -->
+<el-button
+  :loading="pageStore.$loading.search"
+  @click="pageStore.search"
+>
+  搜索
+</el-button>
+
+<!-- 保存：UI 层自己决定是否禁用 -->
+<el-button
+  :loading="pageStore.$loading.save"
+  :disabled="pageStore.$loading.save"
+  @click="pageStore.save"
+>
+  保存
+</el-button>
+```
 
-`state()` 返回值定义了推荐的状态边界：
+### 说明
+
+- 框架只做 **loading 追踪**
+- **不自动跳过重复调用**
+- 是否防重复，由 UI 层通过 `:disabled="pageStore.$loading.xxx"` 自己决定
+
+## State / Source Shape 规则
+
+### state
+
+`state()` 返回值定义了推荐的业务状态边界：
 
 - **推荐**：在 `state()` 中声明完整字段，即使初始值为 `null` 或空数组
 - **允许**：通过 `$patch` 动态新增字段（会写入 `$state`，但不会自动成为 `store.xxx` 顶层代理）
 - **注意**：`$reset()` 会清除所有不在 `state()` 中的动态字段
 
+### source
+
+`source()` 返回值定义了页面输入 / 原始返回的初始 shape：
+
+- **推荐**：把常见 source 字段预先声明出来，如 `response`、`query`
+- **允许**：运行时动态给 `$source` 增加字段
+- **注意**：`$reset()` 同样会清除所有不在 `source()` 中的动态字段
+
 ```js
+source: () => ({
+  response: null,
+  query: {},
+}),
+
 state: () => ({
   filters: {},
-  list: [],
-  detail: null  // 推荐：先声明为 null，而不是运行时再 $patch 进去
+  selectedIds: [],
+  detail: null,
 })
 ```
 
@@ -203,15 +441,15 @@ state: () => ({
 
 ## 适用场景
 
-- 仪表盘页面 — 多模块共享筛选条件、加载状态
-- 漏斗/留存等分析详情页 — 复杂交互 + 异步数据 + 生命周期管理
-- 大型配置页 — 多 tab/多步骤表单的状态统一管理
-- keep-alive 业务页 — 需要 activate/deactivate 感知的页面
-- 微前端子应用 — 页面作用域隔离，不污染宿主全局状态
+- 仪表盘页面 —— 多模块共享筛选条件、加载状态
+- 漏斗 / 留存等分析详情页 —— 复杂交互 + 异步数据 + 页面可见性管理
+- 大型配置页 —— 多 tab / 多步骤表单的状态统一管理
+- keep-alive 业务页 —— 需要 init / enter / leave 感知的页面
+- 微前端子应用 —— 页面作用域隔离，不污染宿主全局状态
 
 ## 不适用场景
 
-- 全局用户信息、权限、路由等 → 用 Vuex
+- 全局用户信息、权限、路由等 → 用 Vuex / Pinia
 - 简单页面的小 data 管理 → 用组件 data 就够了
 - 需要同 id 多实例并存 → 当前版本不支持
 
@@ -222,11 +460,9 @@ state: () => ({
 ```js
 actions: {
   async fetchData() {
-    this.loading = true
     const data = await api.getData()
     // 即使页面已销毁，下面的赋值也会被自动静默，不会报错
-    this.list = data
-    this.loading = false
+    this.$source.response = data
   }
 }
 ```
@@ -246,52 +482,66 @@ storeRegistry.forEach((store, id) => {
 })
 ```
 
-## 从 v0.2.x 升级
+## 从 v0.3.x 升级
 
 ### Breaking Changes
 
-**1. `$reset()` 语义变严格**
-
-v0.2.x：只恢复已有字段的值，动态新增字段会残留。
-
-v0.3.0：完全恢复到 `state()` 的 shape，动态字段会被移除。
-
-**2. `watch` 默认不再 deep**
+**1. `lifecycle` 被移除，改为 `init` / `enter` / `leave`**
 
-v0.2.x：所有 watcher 默认 `deep: true`。
-
-v0.3.0：默认 `deep: false`。如果你的 watcher 依赖深层变化检测，需要显式加 `deep: true`。
+v0.3.x：
 
 ```js
-// v0.2.x — 这个能监听到 filters 内部变化
-watch: {
-  'filters'(val) { this.fetchData() }
+lifecycle: {
+  mount() {},
+  unmount() {},
+  activate() {},
+  deactivate() {}
 }
+```
 
-// v0.3.0 — 需要显式声明 deep
-watch: {
-  'filters': {
-    handler(val) { this.fetchData() },
-    deep: true
-  }
+v0.4.x：
+
+```js
+init() {
+  // 只执行一次的初始化（拉字典、注册事件等）
+},
+enter() {
+  // 每次可见时执行（替代 mount + activate）
+},
+leave() {
+  // 每次离开时执行（替代 deactivate + unmount）
 }
 ```
 
-**3. `_disposed` → `$disposed`**
+迁移关系：
+
+- `lifecycle.mount` → `enter`（如果包含一次性逻辑，拆到 `init`）
+- `lifecycle.unmount` → `leave`
+- `lifecycle.activate` → `enter`
+- `lifecycle.deactivate` → `leave`
+
+**2. `$reset()` 现在同时重置 source 和 state**
+
+v0.4.0 中：
 
-`_disposed` 改为公开属性 `$disposed`，语义不变。如果你之前用了 `store._disposed`，替换为 `store.$disposed`。
+- `state` 恢复到 `state()` 初始值
+- `source` 恢复到 `source()` 初始值
+- 不在初始 shape 中的动态字段会被移除
 
 ### New Features
 
-- `bindTo()` 自动 provide — 子组件 `inject: ['pageStore']` 即可获取，不需要 import store 文件
-- `bindTo()` 重复绑定防护 — 同一个组件实例多次调用不会重复注册生命周期
-- 开发环境 warning — watch 缺少 handler、definePageStore 参数错误等场景会有提示
+- `source`：页面输入 / 原始返回与业务状态分离
+- `init`：store 创建后一次性钩子，`$vm` 已可用（v0.4.1）
+- `enter / leave`：更简单的页面可见性生命周期
+- `$setInterval()`：页面级 interval 托管
+- `$loading.xxx`：返回 Promise 的 action 自动追踪 loading
+- `$vm`：只读逃生口，可在 init / enter 中访问 `$route / $router`
 
 ## Roadmap
 
-- **Plugin system** — 可扩展能力（logger、persist、loading tracker）
 - **Keyed instance** — `useStore(vm, scopeKey)` 支持同定义多实例
-- **Page cache strategy** — TTL、revalidate、stale-while-activate
+- **Page cache strategy** — TTL、revalidate、stale-while-enter
+- **More page runtime helpers** — 在不增加心智负担的前提下继续补页面层能力
 
 ## License