Pinia 及其持久化插件的完整使用指南
Pinia 是 Vue 官方推荐的状态管理库，比 Vuex 更简单、更符合组合式 API 的设计理念。结合持久化插件可以实现状态数据的本地存储。
一、安装 Pinia 及其持久化插件
首先需要安装必要的依赖包：
npm install pinia pinia-plugin-persistedstate # 或 yarn add pinia pinia-plugin-persistedstate # 或 pnpm add pinia pinia-plugin-persistedstate
二、基本配置
1. 在 main.js/ts 中配置 Pinia
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
import App from './App.vue'
// 创建 Pinia 实例
const pinia = createPinia()
// 使用持久化插件
pinia.use(piniaPluginPersistedstate)
const app = createApp(App)
// 将 Pinia 挂载到 Vue 应用
app.use(pinia)
app.mount('#app')
2. 创建 Store
在 stores 目录下创建你的 Store 文件，例如 userStore.js：
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
export const useUserStore = defineStore('user', () => {
// 状态
const token = ref('')
const userInfo = ref(null)
// getters
const isLogin = computed(() => !!token.value)
// actions
const login = async (credentials) => {
// 这里应该是你的登录API调用
const res = await api.login(credentials)
token.value = res.token
userInfo.value = res.user
}
const logout = () => {
token.value = ''
userInfo.value = null
}
return {
token,
userInfo,
isLogin,
login,
logout
}
}, {
persist: true // 启用持久化
})
三、在组件中使用 Store
1. 基本使用
<script setup>
import { useUserStore } from '@/stores/user'
const userStore = useUserStore()
</script>
<template>
<div v-if="userStore.isLogin">
欢迎，{{ userStore.userInfo.name }}
<button @click="userStore.logout">退出登录</button>
</div>
<div v-else>
<button @click="userStore.login({username: 'admin', password: '123456'})">
登录
</button>
</div>
</template>
2. 使用 storeToRefs 解构
注意：storeToRefs 只能解构出状态（变量）和计算属性，而不能解构出方法
如果需要解构方法，直接用例如 let {getList,onDelete}=userStore() 解构且它只能解构方法
<script setup>
import { storeToRefs } from 'pinia'
import { useUserStore } from '@/stores/user'
const userStore = useUserStore()
// 使用 storeToRefs 解构保持响应式
const { token, userInfo, isLogin } = storeToRefs(userStore)
</script>
四、持久化配置详解（可选）
1. 基本配置
{
persist: {
key: 'user', // 存储的键名，默认为 store 的 id
storage: localStorage, // 存储位置，默认为 localStorage
paths: ['token', 'userInfo'], // 指定要持久化的状态，默认全部
serializer: { // 序列化配置
serialize: JSON.stringify,
deserialize: JSON.parse
}
}
}
2. 自定义存储键名
{
persist: {
key: 'my-app-user' // 自定义存储键名
}
}
3. 部分状态持久化
{
persist: {
paths: ['token'] // 只持久化 token
}
}
4. 使用 sessionStorage
{
persist: {
storage: sessionStorage // 使用 sessionStorage 替代 localStorage
}
}
5. 自定义序列化（如加密）
import { encrypt, decrypt } from '@/utils/crypto'
{
persist: {
serializer: {
serialize: (value) => encrypt(JSON.stringify(value)),
deserialize: (value) => JSON.parse(decrypt(value))
}
}
}
6. 多存储方式组合
{
persist: [
{
key: 'user-info',
paths: ['userInfo'],
storage: localStorage
},
{
key: 'user-token',
paths: ['token'],
storage: sessionStorage
}
]
}
推荐使用持久化的场景
1. 用户身份认证
// userStore.js
export const useUserStore = defineStore('user', () => {
const token = ref('')
return { token }
}, {
persist: true // 保持登录状态
})
-
作用：避免用户刷新页面后需要重新登录。
2. 购物车/草稿数据
// cartStore.js
persist: {
paths: ['items'], // 仅持久化商品列表
storage: sessionStorage // 会话级存储
}
-
作用：防止意外关闭页面导致数据丢失。
3. UI 偏好设置
// settingsStore.js
persist: {
key: 'app-settings', // 自定义键名
paths: ['theme', 'language'] // 主题和语言设置
}
-
作用：记住用户的主题、语言等偏好。
五、高级用法
1. 跨 Store 调用
import { defineStore } from 'pinia'
import { useUserStore } from './userStore'
export const useCartStore = defineStore('cart', () => {
const userStore = useUserStore()
const cartItems = ref([])
const loadCart = async () => {
if (userStore.isLogin) {
// 调用 API 获取购物车数据
cartItems.value = await api.getCart(userStore.token)
}
}
return { cartItems, loadCart }
}, {
persist: true
})
2. 重置 Store 状态
const userStore = useUserStore() // 重置为初始状态 userStore.$reset()
3. 订阅状态变化
userStore.$subscribe((mutation, state) => {
// 当状态变化时执行
console.log('状态变化:', mutation, state)
})