super_video/PINIA_GUIDE.md

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 文件:

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

<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. 高级持久化配置

如果只想持久化部分状态:

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 官方文档
• pinia-plugin-persistedstate 文档