pinia-skilld

[email protected]

源代码引用使用基于已准备的 pinia 4.0.3 源代码的包相对路径：package.json、README.md、dist/pinia.js（运行时）、dist/pinia.d.ts（类型）。其他引用为官方文档 URL。

要求

• Vue ^3.5.11 peer [package.json:62]。自 v3 起不再支持 Vue 2。
• @vue/devtools-api ^8.1.5 是必需且不可选的 peer [package.json:60-68]。请与 pinia 一起安装：npm install pinia @vue/devtools-api [README.md:108-111]，参见 v4.0.0 发布说明。
• TypeScript >=5.6.0 可选 peer [package.json:69-71]。
• 仅 ESM 的包："type": "module"，单一导出 . 指向 dist/pinia.js [package.json:42,47-50]。v4 移除了 CJS 解析；require() 回退会失效。
• @pinia/nuxt 1.x 和 @pinia/testing 2.x 是 pinia 4 的配套版本（https://github.com/vuejs/pinia/releases）。

安装和设置

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const pinia = createPinia()
const app = createApp(App)
app.use(pinia)
app.mount('#app')

摘自 [README.md:119-130]。在客户端开发环境中，createPinia() 会自行注册开发者工具插件 [dist/pinia.js:832,847]。

定义存储

有两种语法。两者的第一个参数都是唯一字符串 id [dist/pinia.d.ts:645,653]。

import { defineStore } from 'pinia'

// Option store: state/getters/actions
export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    doubleCount: (state) => state.count * 2,
  },
  actions: {
    increment() {
      this.count++
    },
  },
})

// Setup store: refs are state, computed are getters, functions are actions
export const useTodos = defineStore('todos', () => {
  const todos = ref<Todo[]>([])
  const done = computed(() => todos.value.filter((t) => t.done))
  function add(todo: Todo) {
    todos.value.push(todo)
  }
  return { todos, done, add }
})

设置式存储的规则 [dist/pinia.js:1178-1202]：

• ref() 和 reactive() 会变为状态。
• computed() 会变为 getter。
• 函数会变为 action，并自动包装以支持 $onAction。
• 返回所有状态属性。Pinia 只会识别返回的状态，因此私有状态会破坏 SSR 水合和开发者工具。

设置函数会接收辅助函数：defineStore('id', ({ action }) => { ... }) [dist/pinia.js:1177, dist/pinia.d.ts:628-638]。在存储内部调用时，action(fn, name?) 会让辅助函数可被 $onAction 跟踪。很少需要使用；它适用于 Pinia Colada 等高级场景。

使用存储

在 setup()（或任何组合式函数）中调用 useStore()。每次调用都会返回同一个存储实例。

const counter = useCounterStore()

counter.count++            // direct state mutation
counter.doubleCount        // getter
counter.increment()        // action

const { count, doubleCount } = storeToRefs(counter) // refs for destructuring

storeToRefs() 会将状态和 getter 转换为 refs。它会忽略 action 和非响应式属性 [dist/pinia.js:1475-1489]。需要响应式时，请使用它进行解构，切勿直接使用 toRefs() 或 ...store。

常见操作：

• 使用 store.$patch(obj) 或 $patch(fn) 将更改归为一条开发者工具记录。函数形式必须同步 [dist/pinia.d.ts:219-225]，适用于数组、Map 和 Set 的编辑 [dist/pinia.js:964-975]。
• 只有选项式存储才有 $reset()。在设置式存储中，它会在开发环境抛出异常 [dist/pinia.js:1085-1087]；请在返回的对象中自行实现 $reset。
• 赋值 store.$state = {...} 不会替换状态；它会在内部调用 $patch [dist/pinia.js:1207-1216]。
• 在 state() 中声明每个状态键（或从 setup 返回），即使初始值为 undefined 也要声明。之后新增的键不会是响应式的。
• 在组件外部传入 pinia 实例：useStore(pinia)。在服务器端这是必需的；省略它可能导致跨请求状态污染 [dist/pinia.js:37-39]。

详情：存储、订阅。

版本说明和迁移

v4.0.0，仅在技术层面存在破坏性变更（https://github.com/vuejs/pinia/releases/tag/v4.0.0）：

• 发行包仅包含 ESM。
• @vue/devtools-api 升级到 v8，现在必须安装。
• 错误和开发警告已重构为使用 Nostics 诊断，代码为 PINIA_R1001 到 PINIA_R1007 [dist/pinia.js:18-56]。参见诊断。
• piniaSymbol 现在属于公开导出 [dist/pinia.js:1491]。
• storeToRefs() 会妥善跳过 nullish 值；$subscribe() 会忽略重复回调，而不是再添加一个 watcher。

v3.0.0 中仍然适用的内容（https://pinia.vuejs.org/cookbook/migration-v2-v3.html）：

• 已移除仅接受对象的 defineStore({ id: 'x', ... }) 签名。请使用 defineStore('x', { ... })。
• 已移除 PiniaStorePlugin 类型。请使用 PiniaPlugin。
• 已停止支持 Vue 2。Vue 2 用户请继续使用 pinia v2。

参考文件

• API 概览：所有公开导出及其签名和类型辅助工具。
• 存储：状态、getter、操作、类型、组合存储和 HMR。
• 订阅：$subscribe、$onAction、MutationType、分离和刷新选项。
• 插件：pinia.use()、上下文、类型扩展、新状态和选项。
• SSR：水合、skipHydrate、按请求创建 pinia、Nuxt。
• 测试：setActivePinia、@pinia/testing 2.x 用法。
• Options API：无需使用 setup() 的 map 辅助工具。
• 诊断：仅限开发环境的 PINIA_R100x 目录及修复建议。

官方文档：https://pinia.vuejs.org