# 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/)