@deppon/deppon-pinia

@deppon/deppon-pinia

Pinia 状态管理封装包，提供统一的 Pinia 配置和便捷的使用方式。

安装

npm install @deppon/deppon-pinia

依赖说明：

• pinia 已声明为 peerDependencies，如果宿主项目已安装 pinia@^2.1.7，将优先使用宿主项目的版本，避免版本冲突
• 如果宿主项目未安装 pinia，会自动安装（因为也在 dependencies 中）
• 建议宿主项目显式安装 pinia@^2.1.7 以确保版本一致性

特性

• 🎯 统一的 Pinia 配置管理
• 📊 集成状态变更日志追踪（可选）
• 🔌 支持 Vue 3 Composition API 和 Options API
• 🎨 提供便捷的 composable 函数
• 📦 轻量级封装，不改变 Pinia 原有 API

基础使用

1. 安装插件

在 Vue 应用中安装插件：

import { createApp } from 'vue';
import { default as VuePlugin } from '@deppon/deppon-pinia';

const app = createApp(App);

// 基础安装
app.use(VuePlugin);

app.mount('#app');

2. 创建 Store

// stores/user.js
// 推荐：从 @deppon/deppon-pinia 导入
import { defineStore } from '@deppon/deppon-pinia';

// 或者从 pinia 导入（也支持）
// import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
    state: () => ({
        name: '',
        age: 0,
    }),
    getters: {
        displayName: state => {
            return state.name || '未命名';
        },
    },
    actions: {
        setName(name) {
            this.name = name;
        },
        setAge(age) {
            this.age = age;
        },
    },
});

3. 在组件中使用

Composition API

<script setup>
import { useUserStore } from '@/stores/user';
import { storeToRefs } from '@deppon/deppon-pinia';

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

const handleUpdate = () => {
    userStore.setName('张三');
    userStore.setAge(25);
};
</script>

<template>
    <div>
        <p>姓名: {{ name }}</p>
        <p>年龄: {{ age }}</p>
        <button @click="handleUpdate">更新</button>
    </div>
</template>

Options API

<script>
import { useUserStore } from '@/stores/user';

export default {
    computed: {
        ...mapState(useUserStore, ['name', 'age']),
    },
    methods: {
        ...mapActions(useUserStore, ['setName', 'setAge']),
        handleUpdate() {
            this.setName('张三');
            this.setAge(25);
        },
    },
};
</script>

高级配置

集成日志追踪

如果需要在状态变更时进行埋点追踪，可以传入日志实例：

import { createApp } from 'vue';
import { default as VuePlugin } from '@deppon/deppon-pinia';
import { useLog } from '@deppon/deppon-log';

const app = createApp(App);
const log = useLog();

// 安装插件并配置日志追踪
app.use(VuePlugin, {
    log: log,
});

app.mount('#app');

配置后，每次状态变更都会自动触发日志事件 pinia_state_change。

使用 createDepponPinia 创建自定义实例

如果需要更精细的控制，可以直接使用 createDepponPinia：

import { createApp } from 'vue';
import { createDepponPinia } from '@deppon/deppon-pinia';
import { useLog } from '@deppon/deppon-log';

const app = createApp(App);
const log = useLog();

const pinia = createDepponPinia({
    log: log,
    beforeCreate: store => {
        console.log('Store 创建前:', store.$id);
    },
    afterCreate: store => {
        console.log('Store 创建后:', store.$id);
    },
});

app.use(pinia);
app.mount('#app');

使用 usePinia 获取实例

import { usePinia } from '@deppon/deppon-pinia';

export default {
    setup() {
        const pinia = usePinia();

        // 访问所有 stores
        console.log(pinia.state.value);

        return {};
    },
};

API

Vue 插件

• VuePlugin - Vue 插件，用于安装到 Vue 应用

核心函数

• createDepponPinia(options) - 创建增强的 Pinia 实例
  • options.log - 日志实例（可选）
  • options.beforeCreate - Store 创建前的钩子函数（可选）
  • options.afterCreate - Store 创建后的钩子函数（可选）

Composition API

• usePinia() - 获取 Pinia 实例
• useStore(store) - 使用 Store（等同于 Pinia 的 useStore）
• storeToRefs(store) - 将 Store 转换为 refs（等同于 Pinia 的 storeToRefs）

Options API

• this.$pinia - 访问 Pinia 实例（需要安装插件）

持久化存储

如果需要持久化存储功能，建议使用 pinia-plugin-persistedstate：

npm install pinia-plugin-persistedstate

import { createPinia } from 'pinia';
import { createPersistedState } from 'pinia-plugin-persistedstate';

const pinia = createPinia();
pinia.use(createPersistedState());

app.use(pinia);

注意事项

• 本包是对 Pinia 的轻量级封装，不会改变 Pinia 的原有 API
• 所有 Pinia 的原生功能都可以正常使用
• 日志追踪功能是可选的，需要传入日志实例才会生效
• 建议在项目入口文件中统一安装插件，确保全局可用

更多信息

• Pinia 官方文档
• Vue 3 文档