Vue3 状态管理新选择：Pinia 完全指南与实战示例

前言

在 Vue3 生态中，Pinia 作为新一代状态管理库，凭借其简洁的 API、完整的 TypeScript 支持和灵活的扩展性，逐渐成为开发者的首选。本文将从基础到实战，带你全面掌握 Pinia 的核心特性与应用场景，通过购物车案例深度解析其使用方法。

一、为什么选择 Pinia？

Pinia 由 Vuex 核心团队开发，专为 Vue3 设计，兼具以下优势：

更简洁的 API
- 取消 Mutations，直接通过 Actions 修改状态，减少冗余代码（对比 Vuex）[^5^]。
- 扁平化模块结构，无需嵌套模块[^3^]。
更好的开发体验
- 天然支持 Vue DevTools，提供时间旅行、状态追踪等功能[^3^]。
- 支持热模块替换（HMR），修改 Store 无需刷新页面[^2^]。
TypeScript 友好
- 所有 API 均类型安全，享受自动补全与类型推断[^3^][^5^]。
轻量级与灵活性
- 代码体积更小，支持按需加载[^3^]。
- 插件机制可扩展功能（如状态持久化）[^1^]。

二、快速上手

1. 安装与配置

bash 复制代码

# 使用 npm 或 yarn 安装
npm install pinia
# 或者
yarn add pinia

javascript 复制代码

// main.js
import { createApp } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';

const app = createApp(App);
const pinia = createPinia(); // 创建 Pinia 实例
app.use(pinia); // 挂载到 Vue 应用
app.mount('#app');

2. 创建第一个 Store

javascript 复制代码

// stores/counter.js
import { defineStore } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
  getters: {
    doubleCount(state) {
      return state.count * 2;
    },
  },
  actions: {
    increment() {
      this.count++;
    },
    async fetchData() {
      // 模拟异步操作
      const data = await new Promise((resolve) => {
        setTimeout(() => resolve(10), 1000);
      });
      this.count = data;
    },
  },
});

三、核心概念与使用

1. State：响应式状态容器

javascript 复制代码

// 定义 State
state: () => ({
  goodsList: [
    { id: 1, name: '手机', price: 3000, quantity: 1 },
    { id: 2, name: '耳机', price: 200, quantity: 2 },
  ],
  total: 0,
}),

2. Getters：计算属性

javascript 复制代码

// 定义 Getters
getters: {
  cartTotal(state) {
    return state.goodsList.reduce((total, item) => {
      return total + item.price * item.quantity;
    }, 0);
  },
},

3. Actions：状态修改逻辑

javascript 复制代码

// 定义 Actions
actions: {
  addItem(item) {
    const existing = this.goodsList.find((i) => i.id === item.id);
    if (existing) {
      existing.quantity += item.quantity;
    } else {
      this.goodsList.push({ ...item });
    }
    this.updateTotal();
  },
  updateTotal() {
    this.total = this.cartTotal;
  },
},

四、实战案例：购物车系统

场景描述

实现购物车的核心功能：添加商品、删除商品、计算总价、状态持久化。

1. 创建 Store

javascript 复制代码

// stores/cart.js
import { defineStore } from 'pinia';
import { ref } from 'vue';

export const useCartStore = defineStore('cart', {
  state: () => ({
    items: ref([]), // 使用 ref 实现深响应式
    total: 0,
  }),
  getters: {
    itemCount(state) {
      return state.items.length;
    },
  },
  actions: {
    addItem(product) {
      const existing = this.items.find((item) => item.id === product.id);
      if (existing) {
        existing.quantity += product.quantity;
      } else {
        this.items.push({ ...product });
      }
      this.calculateTotal();
    },
    removeItem(productId) {
      this.items = this.items.filter((item) => item.id !== productId);
      this.calculateTotal();
    },
    calculateTotal() {
      this.total = this.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
    },
  },
});

2. 在组件中使用

vue 复制代码

<!-- CartComponent.vue -->
<template>
  <div>
    <h2>购物车</h2>
    <p>商品数量: {{ itemCount }}</p >
    <p>总价: ￥{{ total }}</p >
    <ul>
      <li v-for="item in items" :key="item.id">
        {{ item.name }} - ￥{{ item.price }} x {{ item.quantity }}
        <button @click="remove(item.id)">删除</button>
      </li>
    </ul>
    <button @click="addTestItem">添加测试商品</button>
  </div>
</template>

<script setup>
import { useCartStore } from '@/stores/cart';

const cart = useCartStore();

// 获取状态
const items = computed(() => cart.items);
const total = computed(() => cart.total);
const itemCount = computed(() => cart.itemCount);

// 调用 Actions
function remove(id) {
  cart.removeItem(id);
}

function addTestItem() {
  cart.addItem({ id: 3, name: '平板', price: 2000, quantity: 1 });
}
</script>

3. 状态持久化（插件）

bash 复制代码

npm install pinia-plugin-persist

javascript 复制代码

// main.js
import { createPinia } from 'pinia';
import piniaPluginPersist from 'pinia-plugin-persist';

const pinia = createPinia();
pinia.use(piniaPluginPersist); // 注册持久化插件

// 在 Store 中启用持久化
export const useCartStore = defineStore('cart', {
  persist: true, // 开启持久化
  // ...其他配置
});

五、高级特性与最佳实践

1. 模块化管理

将不同功能的状态拆分为多个 Store 文件：

javascript 复制代码

// stores/user.js
export const useUserStore = defineStore('user', {
  state: () => ({
    isLoggedIn: false,
    info: null,
  }),
  actions: {
    login(userInfo) {
      this.isLoggedIn = true;
      this.info = userInfo;
    },
  },
});

2. 插件机制

自定义插件示例（统一添加版本号）

javascript 复制代码

// plugins/version.js
function versionPlugin({ store }) {
  store.$version = '1.0.0'; // 为每个 Store 添加 $version 属性
}

// 注册插件
pinia.use(versionPlugin);

订阅 Store 变化

javascript 复制代码

function watchPlugin({ store }) {
  store.$subscribe((mutation, state) => {
    console.log('状态变更：', mutation, state);
  });
}

3. 优化建议

避免直接修改 State：始终通过 Actions 修改状态，保证逻辑集中。
**使用 <math xmlns="http://www.w3.org/1998/Math/MathML"> p a t c h 批量更新 ∗ ∗ ：对于多字段更新，优先使用 ' t h i s . patch 批量更新**：对于多字段更新，优先使用 `this. </math>patch批量更新∗∗：对于多字段更新，优先使用'this.patch({ count: 1, name: 'test' })`。
解构时保留响应式 ：使用 storeToRefs 转换 Store 为 Refs，避免丢失响应式。

六、总结与展望

Pinia 以其轻量级、灵活和强大的扩展性，成为 Vue3 状态管理的优选方案。通过本文的购物车案例，你已掌握：

基础 State、Getters、Actions 的使用
组件与 Store 的交互方式
插件扩展与持久化
模块化与代码复用

未来可进一步探索：

结合 Composition API 实现更复杂的状态管理
自定义插件实现权限控制、日志记录等功能
搭配 Vuex 迁移工具逐步重构老项目

参考资料

Pinia 官方文档
Vue DevTools 扩展
pinia-plugin-persist