Weapp-vite

Appearance

Store API（状态管理） ​

以下条目来源于 packages-runtime/wevu/src/store/index.ts 的模块导出，以及 defineStore() 返回实例和 createStore() 返回 Manager 的公共契约。

Wevu Store 对齐 Pinia 的主要使用心智，但不是 Pinia 的完整实现。createStore()、Manager 安装行为、订阅时机和小程序响应式更新均以本页契约为准。

核心函数 ​

defineStore() ​

类型签名： typeof import('wevu/store')['defineStore']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 类型入口：DefineStoreOptions
  • 用途：定义 store（setup 风格或 option 风格）。

createStore() ​

类型签名： typeof import('wevu/store')['createStore']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

示例： 见 本组示例。

  • 类型入口：StoreManager
  • 用途：创建 store 管理器（可用于作用域隔离和测试隔离）。

storeToRefs() ​

类型签名： typeof import('wevu/store')['storeToRefs']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 类型入口：StoreToRefsResult
  • 用途：将 store 状态转换为 refs，避免解构丢失响应性。

本组示例 ​

Setup Store 优先返回 Ref、computed 和 Action；状态解构使用 storeToRefs()。

ts
import { computed, createStore, defineStore, ref, storeToRefs } from 'wevu'

const manager = createStore()
const useCounter = defineStore('counter', () => {
  const count = ref(0)
  const doubled = computed(() => count.value * 2)
  const increment = () => count.value += 1
  return { count, doubled, increment }
})

const counter = useCounter(manager)
const { count, doubled } = storeToRefs(counter)

Store 实例 API ​

$id ​

类型签名： ReturnType<ReturnType<typeof defineStore>>['$id']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：读取 defineStore() 声明的 Store 标识。
  • 适用：Setup Store 与 Options Store。

$state ​

类型签名： ReturnType<ReturnType<typeof defineStore>>['$state']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：读取或浅合并替换 Options Store 的响应式 state。
  • 适用：仅 Options Store 的公共类型包含 $state；Setup Store 应直接使用 setup 返回的 state/ref。

$patch() ​

类型签名： ReturnType<ReturnType<typeof defineStore>>['$patch']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：通过部分对象或回调函数批量修改状态。
  • 订阅类型：分别触发 patch object 或 patch function。

$reset() ​

类型签名： ReturnType<ReturnType<typeof defineStore>>['$reset']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：恢复 Store 创建时保存的初始状态快照。
  • 适用：Setup Store 与 Options Store；Setup Store 中不可写的 computed/readonly ref 会被跳过。

$subscribe() ​

类型签名： ReturnType<ReturnType<typeof defineStore>>['$subscribe']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：订阅 Store 状态变化，回调接收 mutation 信息和当前状态。
  • 返回值：取消订阅函数。
  • 选项：支持 { detached: true }，用于跨页面生命周期保留订阅。

$onAction() ​

类型签名： ReturnType<ReturnType<typeof defineStore>>['$onAction']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：订阅 Action 调用，可通过 after() 和 onError() 监听成功结果或错误。
  • 返回值：取消订阅函数。

本组示例 ​

实例 API 可以批量更新、重置并观察 mutation 与 Action 结果。

ts
const stopState = counter.$subscribe((mutation, state) => {
  console.log(mutation.type, state.count)
})
const stopAction = counter.$onAction(({ name, after, onError }) => {
  after(result => console.log(name, result))
  onError(error => console.error(name, error))
})

counter.$patch({ count: 2 })
counter.$patch((state) => {
  state.count += 1
})
counter.$reset()
stopState()
stopAction()

Store Manager API ​

manager.install() ​

类型签名： StoreManager['install']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： Pinia 通过 app.use(pinia) 注入 Vue App；Wevu 小程序没有同等插件挂载阶段，install() 仅保留兼容入口。

示例： 见 本组示例。

  • 用途：保留与插件安装心智一致的接口。
  • 差异：小程序环境不需要注册全局插件入口，当前实现不执行额外逻辑。

manager.use() ​

类型签名： StoreManager['use']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：注册 Store 插件；每个新建 Store 会调用插件并传入 { store }。
  • 返回值：当前 StoreManager，支持链式调用。

本组示例 ​

Manager 插件只影响之后创建的 Store，适合隔离测试和注入横切能力。

ts
import { createStore, defineStore } from 'wevu'

const manager = createStore()
manager.use(({ store }) => {
  console.log('created store', store.$id)
})
manager.install()

const useSession = defineStore('session', { state: () => ({ token: '' }) })
const session = useSession(manager)

Options Store 配置 ​

state ​

类型签名： DefineStoreOptions<State, Getters, Actions>['state']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 类型：() => Record<string, any>。
  • 用途：返回每个 Store 的初始响应式状态。

getters ​

类型签名： DefineStoreOptions<State, Getters, Actions>['getters']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：声明派生状态；getter 可接收 state，并可通过 this 访问 state、其他 getters 和 actions。

actions ​

类型签名： DefineStoreOptions<State, Getters, Actions>['actions']

运行时说明： 状态由 Wevu 响应式系统追踪，并随所属页面或组件的渲染批次同步；解构 state/getter 时必须使用 storeToRefs()。

Vue/Pinia 差异： API 心智接近 Pinia，但实现使用 Wevu 响应式与小程序实例作用域；不包含 Pinia devtools、SSR hydration 和完整插件生态。

示例： 见 本组示例。

  • 用途：声明 Store 方法；Action 内的 this 指向 Store 实例，并会触发 $onAction() 订阅。

本组示例 ​

Options Store 的 getter 和 Action 可通过 this 访问同一个 Store。

ts
import { defineStore } from 'wevu'

export const useCart = defineStore('cart', {
  state: () => ({ count: 0, price: 20 }),
  getters: { total: state => state.count * state.price },
  actions: {
    add(quantity = 1) { this.count += quantity },
    clear() { this.count = 0 },
  },
})

Store 类型 ​

StoreManager ​

类型签名：

ts
interface StoreManager {
  install: (app: any) => void
  _stores: Map<string, any>
  use: (plugin: (context: { store: any }) => void) => StoreManager
  _plugins: Array<(context: { store: any }) => void>
}

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：store 根管理器类型。

DefineStoreOptions ​

类型签名：

ts
interface DefineStoreOptions<
  S extends Record<string, any>,
  G extends GetterTree<S>,
  A extends Record<string, any>,
> {
  state: () => S
  getters?: G & Record<string, (state: S) => any> & ThisType<S & StoreGetters<G> & A>
  actions?: A & ThisType<S & StoreGetters<G> & A>
}

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：定义 option 风格 store 的类型约束。

StoreToRefsResult ​

类型签名：

ts
type StoreToRefsResult<T extends Record<string, any>> = {
  [K in keyof T]:
  T[K] extends (...args: any[]) => any
    ? T[K]
    : T[K] extends Ref<infer V>
      ? Ref<V>
      : Ref<T[K]>
}

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：storeToRefs() 返回结果类型。

ActionContext ​

类型签名：

ts
interface ActionContext<TStore = any> {
  name: string
  store: TStore
  args: any[]
  after: (cb: (result: any) => void) => void
  onError: (cb: (error: any) => void) => void
}

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：$onAction 回调上下文。

ActionSubscriber ​

类型签名：

ts
interface ActionSubscriber<TStore = any> {
  (context: ActionContext<TStore>): void
}

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：action 订阅回调签名。

SubscriptionCallback ​

类型签名：

ts
interface SubscriptionCallback<S = any> {
  (mutation: { type: MutationType, storeId: string }, state: S): void
}

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：状态变更订阅回调签名。

StoreSubscribeOptions ​

类型签名：

ts
interface StoreSubscribeOptions {
  /**
   * @description 是否在卸载后仍保留订阅（适用于跨页面生命周期的订阅）
   */
  detached?: boolean
}

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：$subscribe 的订阅选项类型。

MutationType ​

类型签名：

ts
type MutationType = 'patch object' | 'patch function' | 'direct'

运行时说明： 该类型用于约束 Store 类型 的公开契约，不会在运行时产生额外对象；应从 wevu/store 以 import type 导入。

示例： 见 本组示例。

  • 用途：store mutation 类型（'patch object' | 'patch function' | 'direct'）。

本组示例 ​

公开类型适合约束插件、订阅器和 Action 观察工具。

ts
import type { ActionSubscriber, StoreManager, SubscriptionCallback } from 'wevu'

const logMutation: SubscriptionCallback<{ count: number }> = (mutation, state) => {
  console.log(mutation.storeId, mutation.type, state.count)
}

const logAction: ActionSubscriber = ({ name, args }) => console.log(name, args)
declare const manager: StoreManager
manager.use(({ store }) => {
  store.$subscribe(logMutation)
  store.$onAction(logAction)
})

Released under the MIT License.

Copyright © 2024-present sonofmagic