Pinia 详细使用手册

一、Pinia 核心概述Pinia 是 Vue 官方推荐的新一代状态管理库专为 Vue3 设计也兼容 Vue2。它抛弃了 Vuex 的 Mutations仅保留 State、Getters、ActionsAPI 极简、TypeScript 支持完善、轻量高效约 1KB是 Vue 项目状态管理的首选方案。核心优势扁平化模块设计无嵌套结构维护更简单天然支持 TS自动类型推导编码更安全支持组合式Setup与选项式Options两种写法与 Vue DevTools 深度集成支持时间旅行调试支持服务端渲染SSR与状态持久化二、环境安装与初始化1. 安装 Pinia# npm npm install pinia # yarn yarn add pinia # pnpm推荐 pnpm add pinia2. 全局挂载main.ts/main.jsimport { createApp } from vue import { createPinia } from pinia import App from ./App.vue const appcreateApp(App) const piniacreatePinia() // 创建 Pinia 实例 app.use(pinia) // 挂载到 Vue 应用 app.mount(#app)三、Store 定义两种写法Store 是 Pinia 的核心每个 Store 对应一个独立的状态模块用defineStore定义第一个参数为全局唯一 ID。1. 选项式写法Options类似 Vuex// stores/counter.ts import { defineStore } from pinia export const useCounterStoredefineStore(counter, { // State状态数据源必须是函数避免多实例污染 state: () ({ count: 0, name: Pinia }), // Getters计算属性缓存类似组件 computed getters: { // 基础用法接收 state doubleCount: (state) state.count*2, // 访问其他 getter用 this doubleCountPlusOne(): number { return this.doubleCount1 } }, // Actions同步/异步方法类似组件 methods actions: { // 同步修改 increment() { this.count // 直接访问 state }, // 异步修改 async fetchData() { const resawait fetch(/api/data) const dataawait res.json() this.namedata.name } } })2. 组合式写法SetupVue3 风格更灵活支持 Vue 组合式 APIref/reactive/computed// stores/user.ts import { defineStore } from pinia import { ref, computed } from vue export const useUserStoredefineStore(user, () { // State用 ref/reactive 定义 const usernameref(游客) const tokenref() const isLoginref(false) // Getters用 computed 定义 const upperUsernamecomputed(() username.value.toUpperCase()) // Actions用普通函数定义 function login(data: { username: string; token: string }) { username.valuedata.username token.valuedata.token isLogin.valuetrue } function logout() { username.value游客 token.value isLogin.valuefalse } // 返回 state/getters/actions暴露给组件 return { username, token, isLogin, upperUsername, login, logout } })四、组件中使用 Store1. 基础用法直接访问template div p计数{{ counter.count }}/p p双倍计数{{ counter.doubleCount }}/p button clickcounter.increment1/button /div /template script setup // 导入 store import { useCounterStore } from /stores/counter // 创建 store 实例 const counteruseCounterStore() /script {insert\_element\_0\_} ### 2. 解构用法保持响应式 用 storeToRefs 解构避免直接解构丢失响应式 vue template div p用户名{{ username }}/p p大写用户名{{ upperUsername }}/p button clickhandleLogin登录/button /div /template script setup import { useUserStore } from /stores/user import { storeToRefs } from pinia const userStoreuseUserStore() // 解构state/getters 用 storeToRefsactions 直接解构 const { username, upperUsername }storeToRefs(userStore) const { login }userStore function handleLogin() { login({ username: 张三, token: 123456 }) } /script五、State 操作详解1. 直接修改const counteruseCounterStore() counter.count10 // 直接赋值修改2. 批量修改$patch一次性修改多个状态性能更优// 对象形式 counter.$patch({ count: 5, name: New Pinia }) // 函数形式更灵活支持逻辑 counter.$patch((state) { state.count 3 state.name Pro }) {insert\_element\_1\_} ### 3. 重置状态$reset 恢复 state 到初始值 javascript counter.$reset() // { count: 0, name: Pinia }4. 替换整个状态$state直接覆盖 statecounter.$state{ count: 100, name: Replace Pinia }六、Getters 高级用法1. 依赖其他 Gettersgetters: { doubleCount: (state) state.count*2, // 依赖 doubleCount quadrupleCount(): number { return this.doubleCount*2 } }2. 传参 Getters返回函数实现传参getters: { getCountByN: (state) { return (n: number) state.count*n } } // 组件中使用counter.getCountByN(3)3. 访问其他 Store 的 Gettersimport { useUserStore } from ./user getters: { userInfo(): string { const userStoreuseUserStore() return userStore.username } }七、Actions 高级用法1. 异步操作actions: { async getUserInfo(userId: number) { const resawait fetch(/api/user/${userId}) const dataawait res.json() this.userInfodata // 修改 state return data // 返回结果给组件 } } // 组件中调用await userStore.getUserInfo(1)2. 访问其他 Store 的 Actionsimport { useCounterStore } from ./counter actions: { incrementAndLog() { const counterStoreuseCounterStore() counterStore.increment() // 调用其他 store 的 action console.log(计数已增加) } }3. 批量修改状态Actions 中可直接修改多个 state无需$patchactions: { updateUser() { this.username李四 this.token654321 this.isLogintrue } }八、状态持久化pinia-plugin-persistedstate默认状态刷新页面会丢失用持久化插件保存到 localStorage/sessionStorage。1. 安装插件npm install pinia-plugin-persistedstate # yarn add pinia-plugin-persistedstate # pnpm add pinia-plugin-persistedstate2. 全局注册main.tsimport { createPinia } from pinia import piniaPluginPersistedstate from pinia-plugin-persistedstate const piniacreatePinia() pinia.use(piniaPluginPersistedstate) // 注册持久化插件3. 启用持久化Store 中选项式export const useUserStoredefineStore(user, { state: () ({ username: 游客, token: }), persist: true // 开启当前 store 持久化 })组合式export const useUserStoredefineStore(user, () { const usernameref(游客) return { username } }, { persist: true // 开启持久化 })4. 自定义持久化规则persist: { key: user-info, // 自定义存储 key storage: sessionStorage, // 存储位置默认 localStorage paths: [username], // 仅持久化指定字段 // 加密存储敏感数据 serialize: (state) { return JSON.stringify({ ...state, token: btoa(state.token) }) }, deserialize: (value) { const stateJSON.parse(value) state.tokenatob(state.token) return state } }九、模块化与多 Store1. 目录结构推荐src/ ├── stores/ │ ├── index.ts # 统一导出 │ ├── counter.ts │ ├── user.ts │ └── cart.ts2. 统一导出stores/index.tsexport { useCounterStore } from ./counter export { useUserStore } from ./user export { useCartStore } from ./cart3. 组件中导入import { useCounterStore, useUserStore } from /stores十、TypeScript 支持Pinia 天然支持 TS自动类型推导// 选项式自动推导 state/getters/actions 类型 export const useCounterStoredefineStore(counter, { state: () ({ count: 0 }), actions: { increment() { this.count // TS 自动识别 count 类型 } } }) // 组合式ref/computed 自动推导类型 const countref(0) // 类型Refnumber十一、常见问题与避坑解构后丢失响应式必须用storeToRefs解构 state/gettersactions 可直接解构。State 必须是函数避免多个组件实例共享同一状态导致数据污染。持久化异步数据确保异步操作完成后再修改 state否则插件无法监听。全局 ID 唯一defineStore 的第一个参数必须全局唯一否则状态冲突。十二、官方文档与资源官方文档https://pinia.vuejs.org/zh/GitHub 仓库https://github.com/vuejs/pinia持久化插件https://github.com/prazdevs/pinia-plugin-persistedstate