pinia-skilld

[email protected]

ソースの引用では、準備済みの pinia 4.0.3 ソースからのパッケージ相対パスを使用しています：package.json、README.md、dist/pinia.js（ランタイム）、dist/pinia.d.ts（型）。その他の引用は公式ドキュメントの URL です。

要件

• Vue ^3.5.11 がピア依存関係として必要です［package.json:62］。v3 以降、Vue 2 はサポートされていません。
• @vue/devtools-api ^8.1.5 は必須のピア依存関係であり、省略できません［package.json:60-68］。pinia と一緒にインストールしてください：npm install pinia @vue/devtools-api［README.md:108-111］、v4.0.0 リリースノート。
• TypeScript >=5.6.0 は任意のピア依存関係です［package.json:69-71］。
• ESM 専用パッケージです："type": "module"、dist/pinia.js への単一のエクスポート .［package.json:42,47-50］。v4 では CJS の解決方法が削除されています。require() へのフォールバックは機能しません。
• pinia 4 に対応する関連パッケージのバージョンは、@pinia/nuxt 1.x と @pinia/testing 2.x です（https://github.com/vuejs/pinia/releases）。

インストールとセットアップ

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

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

［README.md:119-130］より。クライアント側の開発環境では、createPinia() が開発者ツールのプラグインを自動で登録します［dist/pinia.js:832,847］。

ストアの定義

構文は 2 種類あります。id は一意の文字列で、どちらの構文でも最初の引数です［dist/pinia.d.ts:645,653］。

import { defineStore } from 'pinia'

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

// Setup store: refs are state, computed are getters, functions are actions
export const useTodos = defineStore('todos', () => {
  const todos = ref<Todo[]>([])
  const done = computed(() => todos.value.filter((t) => t.done))
  function add(todo: Todo) {
    todos.value.push(todo)
  }
  return { todos, done, add }
})

セットアップストアのルール［dist/pinia.js:1178-1202］：

• ref() と reactive() はステートになります。
• computed() はゲッターになります。
• 関数はアクションになり、$onAction 用に自動的にラップされます。
• ステートのプロパティはすべて返してください。Pinia が認識するのは返されたステートだけなので、プライベートステートがあると SSR のハイドレーションと開発者ツールが正常に動作しません。

セットアップ関数はヘルパーを受け取ります：defineStore('id', ({ action }) => { ... })［dist/pinia.js:1177、dist/pinia.d.ts:628-638］。action(fn, name?) は、ストア内で呼び出された際にヘルパー関数を $onAction で追跡可能にします。通常は必要ありません。Pinia Colada のような高度なケースを想定しています。

ストアの使用

setup()（または任意のコンポーザブル）内で useStore() を呼び出します。呼び出すたびに同じストアインスタンスが返されます。

const counter = useCounterStore()

counter.count++            // direct state mutation
counter.doubleCount        // getter
counter.increment()        // action

const { count, doubleCount } = storeToRefs(counter) // refs for destructuring

storeToRefs() はステートとゲッターを ref に変換します。アクションとリアクティブでないプロパティは無視します［dist/pinia.js:1475-1489］。リアクティビティが必要な場合は、通常の toRefs() や ...store ではなく、これを使って分割代入してください。

一般的な操作：

• store.$patch(obj) または $patch(fn) を使うと、変更を開発者ツールの 1 つのエントリーにまとめられます。関数形式は同期処理である必要があり［dist/pinia.d.ts:219-225］、配列、Map、Set の編集に適しています［dist/pinia.js:964-975］。
• $reset() があるのはオプションストアだけです。セットアップストアでは、開発環境で呼び出すとエラーになります［dist/pinia.js:1085-1087］。返すオブジェクト内に独自の $reset を実装してください。
• store.$state = {...} を代入してもステートは置き換わりません。内部で $patch が呼び出されます［dist/pinia.js:1207-1216］。
• 初期値が undefined の場合でも、すべてのステートキーを state() で宣言するか、セットアップから返してください。後から追加したキーはリアクティブになりません。
• コンポーネント外では、Pinia インスタンスを渡してください：useStore(pinia)。サーバーでは必須です。省略すると、リクエスト間でステートが混在するおそれがあります［dist/pinia.js:37-39］。

詳細：ストア、サブスクリプション。

バージョン情報と移行

v4.0.0 での変更点。技術的な破壊的変更のみです（https://github.com/vuejs/pinia/releases/tag/v4.0.0）：

• ESM 専用の配布形式。
• @vue/devtools-api が v8 にアップグレードされ、インストールが必須になりました。
• エラーと開発時の警告を Nostics の診断機能に移行しました。コードは PINIA_R1001 から PINIA_R1007 です［dist/pinia.js:18-56］。診断を参照してください。
• piniaSymbol が公開エクスポートに追加されました［dist/pinia.js:1491］。
• storeToRefs() は nullish 値を問題なくスキップするようになりました。$subscribe() は重複したコールバックを無視し、2 つ目のウォッチャーを追加しません。

v3.0.0 から引き続き該当する変更（https://pinia.vuejs.org/cookbook/migration-v2-v3.html）：

• defineStore({ id: 'x', ... }) のオブジェクトのみの構文は削除されました。defineStore('x', { ... }) を使用してください。
• PiniaStorePlugin 型は削除されました。PiniaPlugin を使用してください。
• Vue 2 のサポートは終了しました。Vue 2 を使用する場合は pinia v2 を引き続き使用してください。

参考ファイル

• API サーフェス：すべての公開エクスポートとシグネチャ、型ヘルパー。
• ストア：状態、ゲッター、アクション、型付け、ストアの合成、HMR。
• サブスクリプション：$subscribe、$onAction、MutationType、detached オプションと flush オプション。
• プラグイン：pinia.use()、コンテキスト、型付けの拡張、新しい状態とオプション。
• SSR：ハイドレーション、skipHydrate、リクエストごとの pinia、Nuxt。
• テスト：setActivePinia、@pinia/testing 2.x の使い方。
• Options API：setup() を使わないマップヘルパー。
• 診断：修正方法を含む、開発時のみ使用する PINIA_R100x カタログ。

公式ドキュメント：https://pinia.vuejs.org