@wlydfe/pinia-plus

一个增强版的 Pinia 状态管理解决方案，开箱即用，内置常用插件和实用功能。

✨ 特性

• 🚀 开箱即用 - 预配置 Pinia 实例，无需额外设置
• 💾 状态持久化 - 内置 pinia-plugin-persistedstate 插件
• 🔄 Setup Store 重置 - 支持 Setup 语法下的 store 状态重置
• 🗑️ 批量管理 - 提供批量重置和清理 store 的工具函数
• 📦 Tree-shakable - 基于 ESM，支持按需导入
• 🦾 完整类型支持 - 使用 TypeScript 编写，提供完整类型定义
• ⚡ 现代构建 - 使用 Unbuild 构建，输出优化的代码

📦 安装

# pnpm
pnpm add @wlydfe/pinia-plus pinia

# npm
npm install @wlydfe/pinia-plus pinia

# yarn
yarn add @wlydfe/pinia-plus pinia

🚀 快速开始

基础使用

// main.ts
import { createApp } from 'vue'
import { createPiniaPlus } from '@wlydfe/pinia-plus'
import App from './App.vue'

const app = createApp(App)
const pinia = createPiniaPlus()
app.use(pinia)
app.mount('#app')

定义 Store

// stores/user.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useUserStore = defineStore(
  'user',
  () => {
    const name = ref('')
    const age = ref(0)

    const setUser = (newName: string, newAge: number) => {
      name.value = newName
      age.value = newAge
    }

    return {
      name,
      age,
      setUser,
    }
  },
  {
    // 启用状态持久化
    persist: true,
  },
)

在组件中使用

<template>
  <div>
    <p>姓名: {{ name }}</p>
    <p>年龄: {{ age }}</p>
    <button @click="updateUser">更新用户</button>
    <button @click="resetUser">重置用户</button>
  </div>
</template>

<script setup lang="ts">
import { storeToRefs } from 'pinia'
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()
const { name, age } = storeToRefs(userStore)

const updateUser = () => {
  userStore.setUser('张三', 25)
}

const resetUser = () => {
  // 使用内置的 $reset 方法重置状态（在 Setup 语法下也能正常工作）
  userStore.$reset()
}
</script>

🔧 API 参考

createPiniaPlus

import { createPiniaPlus } from '@wlydfe/pinia-plus'

const pinia = createPiniaPlus()

创建一个预配置的 Pinia 实例，已安装以下插件：

• pinia-plugin-persistedstate - 状态持久化插件
• resetPlugin - Setup Store 重置插件

其他导出

import { clearAllStoresState, setPiniaInstance } from '@wlydfe/pinia-plus'

• clearAllStoresState - 彻底清理所有 store 的数据（内存状态 + 持久化存储）
• setPiniaInstance - 设置 Pinia 实例供管理器使用（通常不需要手动调用，createPiniaPlus 会自动设置）

类型导出

import type { PiniaPlugin, PiniaPluginContext, PersistenceOptions } from '@wlydfe/pinia-plus'

• PiniaPlugin - Pinia 插件类型
• PiniaPluginContext - Pinia 插件上下文类型
• PersistenceOptions - 持久化配置选项类型

注意：虽然 @wlydfe/pinia-plus 仍然提供默认导出的 pinia 实例以保持向后兼容，但推荐使用 createPiniaPlus() 函数来创建实例，这样可以更好地控制实例的生命周期。

🎯 内置插件

Reset 插件

为使用 Setup 语法定义的 store 提供 $reset 方法，可以将 store 状态重置为初始值。

import { defineStore } from 'pinia'
import { ref } from 'vue'

const useCountStore = defineStore('count', () => {
  const count = ref(0)
  const increment = () => count.value++

  return { count, increment }
})

// 在组件中使用
const countStore = useCountStore()
countStore.increment() // count: 1
countStore.$reset() // count: 0 (重置为初始值)

状态持久化

内置 pinia-plugin-persistedstate 插件，支持将 store 状态持久化到 localStorage。

import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useSettingsStore = defineStore(
  'settings',
  () => {
    const theme = ref('light')
    const language = ref('zh-CN')

    return { theme, language }
  },
  {
    persist: {
      key: 'app-settings',
      storage: sessionStorage, // 可选择存储方式
      paths: ['theme'], // 可选择持久化的字段
    },
  },
)

Store 批量管理

提供了批量管理所有 store 的工具函数，适用于退出登录等场景。

import { clearAllStoresState } from '@wlydfe/pinia-plus'

// 彻底清理所有 store 的数据（内存状态 + 持久化存储）
clearAllStoresState()

该函数会：

1. 重置所有 store 的内存状态（调用每个 store 的 $reset 方法）
2. 清理所有 store 的持久化存储（从 localStorage 和 sessionStorage 中删除）

📁 项目结构

@wlydfe/pinia-plus/
├── src/
│   ├── index.ts              # 主入口文件
│   ├── plugins/
│   │   └── reset-plugin.ts   # Reset 插件
│   ├── manager/
│   │   └── index.ts          # Store 管理器
│   └── utils/
│       └── clone-deep.ts     # 深拷贝工具函数
├── example/                  # 使用示例
├── dist/                     # 构建输出
└── README.md

🤝 贡献

欢迎提交 Issues 和 Pull Requests！

📄 许可证

MIT License © 2024-PRESENT wlydfe