Pinia 是什么？

Pinia 起始于 2019 年 11 月左右的一次實(shí)驗(yàn)，其目的是設(shè)計(jì)一個(gè)擁有組合式 API 的 Vue 狀態(tài)管理庫。從那時(shí)起，我們就傾向于同時(shí)支持 Vue 2 和 Vue 3，并且不強(qiáng)制要求開發(fā)者使用組合式 API，我們的初心至今沒有改變。除了安裝和 SSR 兩章之外，其余章節(jié)中提到的 API 均支持 Vue 2 和 Vue 3。雖然本文檔主要是面向 Vue 3 的用戶，但在必要時(shí)會(huì)標(biāo)注出 Vue 2 的內(nèi)容，因此 Vue 2 和 Vue 3 的用戶都可以閱讀本文檔。

為什么你應(yīng)該使用 Pinia？

Pinia 是 Vue 的專屬狀態(tài)管理庫，它允許你跨組件或頁面共享狀態(tài)。如果你熟悉組合式 API 的話，你可能會(huì)認(rèn)為可以通過一行簡(jiǎn)單的 export const state = reactive({}) 來共享一個(gè)全局狀態(tài)。對(duì)于單頁應(yīng)用來說確實(shí)可以，但如果應(yīng)用在服務(wù)器端渲染，這可能會(huì)使你的應(yīng)用暴露出一些安全漏洞。 而如果使用 Pinia，即使在小型單頁應(yīng)用中，你也可以獲得如下功能：

• Devtools 支持
  • 追蹤 actions、mutations 的時(shí)間線
  • 在組件中展示它們所用到的 Store
  • 讓調(diào)試更容易的 Time travel
• 熱更新
  • 不必重載頁面即可修改 Store
  • 開發(fā)時(shí)可保持當(dāng)前的 State
• 插件：可通過插件擴(kuò)展 Pinia 功能
• 為 JS 開發(fā)者提供適當(dāng)?shù)?TypeScript 支持以及自動(dòng)補(bǔ)全功能。
• 支持服務(wù)端渲染

基礎(chǔ)示例

下面就是 pinia API 的基本用法 (為繼續(xù)閱讀本簡(jiǎn)介請(qǐng)確保你已閱讀過了開始章節(jié))。你可以先創(chuàng)建一個(gè) Store：

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


export const useCounterStore = defineStore('counter', {
  state: () => {
    return { count: 0 }
  },
  // 也可以這樣定義
  // state: () => ({ count: 0 })
  actions: {
    increment() {
      this.count++
    },
  },
})

然后你就可以在一個(gè)組件中使用該 store 了：

<script setup>
import { useCounterStore } from '@/stores/counter'
const counter = useCounterStore()
counter.count++
// 自動(dòng)補(bǔ)全！ ?
counter.$patch({ count: counter.count + 1 })
// 或使用 action 代替
counter.increment()
</script>
<template>
  <!-- 直接從 store 中訪問 state -->
  <div>Current Count: {{ counter.count }}</div>
</template>

為實(shí)現(xiàn)更多高級(jí)用法，你甚至可以使用一個(gè)函數(shù) (與組件 setup() 類似) 來定義一個(gè) Store：

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  function increment() {
    count.value++
  }


  return { count, increment }
})

如果你還不熟悉 setup() 函數(shù)和組合式 API，別擔(dān)心，Pinia 也提供了一組類似 Vuex 的 映射 state 的輔助函數(shù)。你可以用和之前一樣的方式來定義 Store，然后通過 mapStores()、mapState() 或 mapActions() 訪問：

const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    double: (state) => state.count * 2,
  },
  actions: {
    increment() {
      this.count++
    },
  },
})


const useUserStore = defineStore('user', {
  // ...
})


export default defineComponent({
  computed: {
    // 其他計(jì)算屬性
    // ...
    // 允許訪問 this.counterStore 和 this.userStore
    ...mapStores(useCounterStore, useUserStore)
    // 允許讀取 this.count 和 this.double
    ...mapState(useCounterStore, ['count', 'double']),
  },
  methods: {
    // 允許讀取 this.increment()
    ...mapActions(useCounterStore, ['increment']),
  },
})

你將會(huì)在核心概念部分了解到更多關(guān)于每個(gè)映射輔助函數(shù)的信息。

為什么取名 Pinia

Pinia (發(fā)音為 /pi?nj?/，類似英文中的 “peenya”) 是最接近有效包名 pi?a (西班牙語中的 pineapple，即“菠蘿”) 的詞。 菠蘿花實(shí)際上是一組各自獨(dú)立的花朵，它們結(jié)合在一起，由此形成一個(gè)多重的水果。 與 Store 類似，每一個(gè)都是獨(dú)立誕生的，但最終它們都是相互聯(lián)系的。 它(菠蘿)也是一種原產(chǎn)于南美洲的美味熱帶水果。

更真實(shí)的示例

這是一個(gè)更完整的 Pinia API 示例，在 JavaScript 中也使用了類型提示。對(duì)于某些開發(fā)者來說，可能足以在不進(jìn)一步閱讀的情況下直接開始閱讀本節(jié)內(nèi)容，但我們?nèi)匀唤ㄗh你先繼續(xù)閱讀文檔的其余部分，甚至跳過此示例，在閱讀完所有核心概念之后再回來。

import { defineStore } from 'pinia'


export const useTodos = defineStore('todos', {
  state: () => ({
    /** @type {{ text: string, id: number, isFinished: boolean }[]} */
    todos: [],
    /** @type {'all' | 'finished' | 'unfinished'} */
    filter: 'all',
    // 類型將自動(dòng)推斷為 number
    nextId: 0,
  }),
  getters: {
    finishedTodos(state) {
      // 自動(dòng)補(bǔ)全！ ?
      return state.todos.filter((todo) => todo.isFinished)
    },
    unfinishedTodos(state) {
      return state.todos.filter((todo) => !todo.isFinished)
    },
    /**
     * @returns {{ text: string, id: number, isFinished: boolean }[]}
     */
    filteredTodos(state) {
      if (this.filter === 'finished') {
        // 調(diào)用其他帶有自動(dòng)補(bǔ)全的 getters ?
        return this.finishedTodos
      } else if (this.filter === 'unfinished') {
        return this.unfinishedTodos
      }
      return this.todos
    },
  },
  actions: {
    // 接受任何數(shù)量的參數(shù)，返回一個(gè) Promise 或不返回
    addTodo(text) {
      // 你可以直接變更該狀態(tài)
      this.todos.push({ text, id: this.nextId++, isFinished: false })
    },
  },
})

對(duì)比 Vuex

Pinia 起源于一次探索 Vuex 下一個(gè)迭代的實(shí)驗(yàn)，因此結(jié)合了 Vuex 5 核心團(tuán)隊(duì)討論中的許多想法。最后，我們意識(shí)到 Pinia 已經(jīng)實(shí)現(xiàn)了我們?cè)?Vuex 5 中想要的大部分功能，所以決定將其作為新的推薦方案來代替 Vuex。

與 Vuex 相比，Pinia 不僅提供了一個(gè)更簡(jiǎn)單的 API，也提供了符合組合式 API 風(fēng)格的 API，最重要的是，搭配 TypeScript 一起使用時(shí)有非?？煽康念愋屯茢嘀С帧?/p>

RFC

最初，Pinia 沒有經(jīng)過任何 RFC 的流程。我基于自己開發(fā)應(yīng)用的經(jīng)驗(yàn)，同時(shí)通過閱讀其他人的代碼，為使用 Pinia 的用戶工作，以及在 Discord 上回答問題等方式驗(yàn)證了一些想法。 這些經(jīng)歷使我產(chǎn)出了這樣一個(gè)可用的解決方案，并適應(yīng)了各種場(chǎng)景和應(yīng)用規(guī)模。我會(huì)一直在保持其核心 API 不變的情況下發(fā)布新版本，同時(shí)不斷優(yōu)化本庫。

現(xiàn)在 Pinia 已經(jīng)成為推薦的狀態(tài)管理解決方案，它和 Vue 生態(tài)系統(tǒng)中的其他核心庫一樣，都要經(jīng)過 RFC 流程，它的 API 也已經(jīng)進(jìn)入穩(wěn)定狀態(tài)。

對(duì)比 Vuex 3.x/4.x

Vuex 3.x 只適配 Vue 2，而 Vuex 4.x 是適配 Vue 3 的。

Pinia API 與 Vuex(<=4) 也有很多不同，即：

• mutation 已被棄用。它們經(jīng)常被認(rèn)為是極其冗余的。它們初衷是帶來 devtools 的集成方案，但這已不再是一個(gè)問題了。
• 無需要?jiǎng)?chuàng)建自定義的復(fù)雜包裝器來支持 TypeScript，一切都可標(biāo)注類型，API 的設(shè)計(jì)方式是盡可能地利用 TS 類型推理。
• 無過多的魔法字符串注入，只需要導(dǎo)入函數(shù)并調(diào)用它們，然后享受自動(dòng)補(bǔ)全的樂趣就好。
• 無需要?jiǎng)討B(tài)添加 Store，它們默認(rèn)都是動(dòng)態(tài)的，甚至你可能都不會(huì)注意到這點(diǎn)。注意，你仍然可以在任何時(shí)候手動(dòng)使用一個(gè) Store 來注冊(cè)它，但因?yàn)樗亲詣?dòng)的，所以你不需要擔(dān)心它。
• 不再有嵌套結(jié)構(gòu)的模塊。你仍然可以通過導(dǎo)入和使用另一個(gè) Store 來隱含地嵌套 stores 空間。雖然 Pinia 從設(shè)計(jì)上提供的是一個(gè)扁平的結(jié)構(gòu)，但仍然能夠在 Store 之間進(jìn)行交叉組合。你甚至可以讓 Stores 有循環(huán)依賴關(guān)系。
• 不再有可命名的模塊?？紤]到 Store 的扁平架構(gòu)，Store 的命名取決于它們的定義方式，你甚至可以說所有 Store 都應(yīng)該命名。