166 lines
4.0 KiB
Markdown
166 lines
4.0 KiB
Markdown
# Pinia 状态管理使用指南
|
|
|
|
## 概述
|
|
|
|
项目已集成 Pinia 状态管理库和 `pinia-plugin-persistedstate` 插件,支持自动将状态持久化到 localStorage。
|
|
|
|
## 安装的依赖
|
|
|
|
- `pinia`: Vue 官方状态管理库
|
|
- `pinia-plugin-persistedstate`: Pinia 持久化插件
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
src/
|
|
├── stores/
|
|
│ ├── modules/ # 模块化 stores 目录
|
|
│ │ ├── counter.ts # 计数器模块
|
|
│ │ ├── user.ts # 用户信息模块
|
|
│ │ ├── preferences.ts # 偏好设置模块
|
|
│ │ └── example.ts # 综合示例模块
|
|
│ └── index.ts # 统一导出文件
|
|
└── main.ts # Pinia 配置
|
|
```
|
|
|
|
## 基本用法
|
|
|
|
### 1. 创建 Store
|
|
|
|
在 `src/stores/` 目录下创建新的 store 文件:
|
|
|
|
```typescript
|
|
import { defineStore } from 'pinia'
|
|
import { ref } from 'vue'
|
|
|
|
export const useMyStore = defineStore(
|
|
'myStore', // store id,必须唯一
|
|
() => {
|
|
// 使用 Composition API 风格
|
|
const data = ref<string>('')
|
|
|
|
function updateData(newData: string): void {
|
|
data.value = newData
|
|
}
|
|
|
|
return {
|
|
data,
|
|
updateData
|
|
}
|
|
},
|
|
{
|
|
// 启用持久化到 localStorage
|
|
persist: true
|
|
}
|
|
)
|
|
```
|
|
|
|
### 2. 在组件中使用 Store
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
import { useExampleStore } from '@/stores'
|
|
|
|
const store = useExampleStore()
|
|
|
|
// 读取状态
|
|
console.log(store.count)
|
|
console.log(store.userName)
|
|
|
|
// 调用 actions
|
|
store.increment()
|
|
store.setUserName('张三')
|
|
</script>
|
|
|
|
<template>
|
|
<div>
|
|
<p>Count: {{ store.count }}</p>
|
|
<p>User: {{ store.userName }}</p>
|
|
<button @click="store.increment">增加</button>
|
|
</div>
|
|
</template>
|
|
```
|
|
|
|
### 3. 高级持久化配置
|
|
|
|
如果只想持久化部分状态:
|
|
|
|
```typescript
|
|
export const useMyStore = defineStore(
|
|
'myStore',
|
|
() => {
|
|
const persistedData = ref<string>('')
|
|
const temporaryData = ref<string>('')
|
|
|
|
return {
|
|
persistedData,
|
|
temporaryData
|
|
}
|
|
},
|
|
{
|
|
persist: {
|
|
// 自定义 localStorage key
|
|
key: 'my-custom-key',
|
|
// 只持久化指定的状态
|
|
paths: ['persistedData'],
|
|
// 自定义存储方式(默认是 localStorage)
|
|
storage: localStorage
|
|
}
|
|
}
|
|
)
|
|
```
|
|
|
|
## Store 模块化设计
|
|
|
|
项目采用**模块化**设计,将不同职责的状态拆分到独立的 stores:
|
|
|
|
### 已创建的模块化 Stores
|
|
|
|
#### 1. Counter Store (`src/stores/modules/counter.ts`)
|
|
|
|
- 管理计数器状态
|
|
- 提供 increment, decrement, reset 方法
|
|
|
|
#### 2. User Store (`src/stores/modules/user.ts`)
|
|
|
|
- 管理用户基本信息
|
|
- 提供 setUserName, clearUserName 方法
|
|
|
|
#### 3. Preferences Store (`src/stores/modules/preferences.ts`)
|
|
|
|
- 管理用户偏好设置(主题、语言等)
|
|
- 包含 computed getters (isDarkMode, currentLanguage)
|
|
- 提供主题切换、语言设置等方法
|
|
|
|
#### 4. Example Store (`src/stores/modules/example.ts`)
|
|
|
|
- 综合示例,展示所有功能
|
|
- 可作为参考模板
|
|
|
|
### 模块化优势
|
|
|
|
- ✅ **职责单一**: 每个 store 只管理特定领域的状态
|
|
- ✅ **易于维护**: 代码结构清晰,便于定位和修改
|
|
- ✅ **可复用**: 小模块更容易在不同场景复用
|
|
- ✅ **按需加载**: 组件只导入需要的 stores
|
|
- ✅ **类型安全**: 每个模块有独立的类型定义
|
|
|
|
## 持久化特性
|
|
|
|
- 🔄 **自动保存**: 状态变化时自动保存到 localStorage
|
|
- 🚀 **自动恢复**: 页面刷新后自动从 localStorage 恢复状态
|
|
- 🎯 **类型安全**: 完整的 TypeScript 支持
|
|
- ⚙️ **可配置**: 支持自定义持久化策略
|
|
|
|
## 注意事项
|
|
|
|
1. **Store ID 必须唯一**: 每个 store 的第一个参数(store id)必须在应用中唯一
|
|
2. **localStorage 限制**: 浏览器 localStorage 通常有 5-10MB 的存储限制
|
|
3. **敏感数据**: 不要在 localStorage 中存储敏感信息(如密码、token 等)
|
|
4. **序列化限制**: 只能存储可序列化的数据(不支持 Function, Symbol 等)
|
|
|
|
## 参考资源
|
|
|
|
- [Pinia 官方文档](https://pinia.vuejs.org/)
|
|
- [pinia-plugin-persistedstate 文档](https://prazdevs.github.io/pinia-plugin-persistedstate/)
|