API 文档 / pinia

模块：pinia ​

枚举 ​

• MutationType

接口 ​

• DefineSetupStoreOptions
• DefineStoreOptions
• DefineStoreOptionsBase
• DefineStoreOptionsInPlugin
• MapStoresCustomization
• Pinia
• PiniaCustomProperties
• PiniaCustomStateProperties
• PiniaPlugin
• PiniaPluginContext
• StoreDefinition
• StoreProperties
• SubscriptionCallbackMutationDirect
• SubscriptionCallbackMutationPatchFunction
• SubscriptionCallbackMutationPatchObject
• _StoreOnActionListenerContext
• _StoreWithState
• _SubscriptionCallbackMutationBase

类型别名 ​

PiniaStorePlugin ​

Ƭ PiniaStorePlugin: PiniaPlugin

扩展每个 store 的插件。

deprecated

使用 PiniaPlugin 代替

StateTree ​

Ƭ StateTree: Record<string | number | symbol, any>

Store 的通用 state

Store ​

Ƭ Store<Id, S, G, A>: _StoreWithState<Id, S, G, A> & UnwrapRef<S> & _StoreWithGetters<G> & _ActionsTree extends A ? {} : A & PiniaCustomProperties<Id, S, G, A> & PiniaCustomStateProperties<S>

创建 store 的 Store 类型。

类型参数 ​

StoreActions ​

Ƭ StoreActions<SS>: SS extends Store<string, StateTree, _GettersTree<StateTree>, infer A> ? A : _ExtractActionsFromSetupStore<SS>

提取一个 store 类型的 action。 对 Setup Store 或 Option Store 都有效。

类型参数 ​

StoreGeneric ​

Ƭ StoreGeneric: Store<string, StateTree, _GettersTree<StateTree>, _ActionsTree>

泛型与 Store 的类型不安全版本。 在访问字符串时不会失败， 这使得编写不在意传递的 store 类型的通用函数更加容易。

StoreGetters ​

Ƭ StoreGetters<SS>: SS extends Store<string, StateTree, infer G, _ActionsTree> ? _StoreWithGetters<G> : _ExtractGettersFromSetupStore<SS>

提取一个 store 类型的 getter。 对 Setup Store 或 Option Store都有效。

类型参数 ​

StoreOnActionListener ​

Ƭ StoreOnActionListener<Id, S, G, A>: (context: StoreOnActionListenerContext<Id, S, G, {} extends A ? _ActionsTree : A>) => void

类型参数 ​

类型声明 ​

▸ (context): void

store.$onAction() 的参数

参数 ​

返回值 ​

void

StoreOnActionListenerContext ​

Ƭ StoreOnActionListenerContext<Id, S, G, A>: _ActionsTree extends A ? _StoreOnActionListenerContext<StoreGeneric, string, _ActionsTree> : { [Name in keyof A]: Name extends string ? _StoreOnActionListenerContext<Store<Id, S, G, A>, Name, A> : never }[keyof A]

传递给 store.$onAction(context => {}) 的回调的上下文对象。 TODO：应该只有Id，Store 和 Action 来生成适当的对象。

类型参数 ​

StoreState ​

Ƭ StoreState<SS>: SS extends Store<string, infer S, _GettersTree<StateTree>, _ActionsTree> ? UnwrapRef<S> : _ExtractStateFromSetupStore<SS>

提取一个 store 类型的 state。 对 Setup Store 或 Option Store 都有效。请注意，它自动解包 refs。

类型参数 ​

SubscriptionCallback ​

Ƭ SubscriptionCallback<S>: (mutation: SubscriptionCallbackMutation<S>, state: UnwrapRef<S>) => void

类型参数 ​

类型声明 ​

▸ (mutation, state): void

订阅的回调

参数 ​

返回值 ​

void

SubscriptionCallbackMutation ​

Ƭ SubscriptionCallbackMutation<S>: SubscriptionCallbackMutationDirect | SubscriptionCallbackMutationPatchObject<S> | SubscriptionCallbackMutationPatchFunction

传递给订阅回调的上下文对象。

类型参数 ​

_ActionsTree ​

Ƭ _ActionsTree: Record<string, _Method>

行动的对象的类型。仅供内部使用。 仅供内部使用

_Awaited ​

Ƭ _Awaited<T>: T extends null | undefined ? T : T extends object & { then: (onfulfilled: F) => any } ? F extends (value: infer V, ...args: any) => any ? _Awaited<V> : never : T

类型参数 ​

_DeepPartial ​

Ƭ _DeepPartial<T>: { [K in keyof T]?: _DeepPartial<T[K]> }

递归的 Partial<T>。 ['$patch']会用到。

仅供内部使用

类型参数 ​

_ExtractActionsFromSetupStore ​

Ƭ _ExtractActionsFromSetupStore<SS>: SS extends undefined | void ? {} : _ExtractActionsFromSetupStore_Keys<SS> extends keyof SS ? Pick<SS, _ExtractActionsFromSetupStore_Keys<SS>> : never

仅供内部使用

类型参数 ​

_ExtractActionsFromSetupStore_Keys ​

Ƭ _ExtractActionsFromSetupStore_Keys<SS>: keyof { [K in keyof SS as SS[K] extends _Method ? K : never]: any }

能够通过 IDE 进行重构的类型。 仅供内部使用

类型参数 ​

_ExtractGettersFromSetupStore ​

Ƭ _ExtractGettersFromSetupStore<SS>: SS extends undefined | void ? {} : _ExtractGettersFromSetupStore_Keys<SS> extends keyof SS ? Pick<SS, _ExtractGettersFromSetupStore_Keys<SS>> : never

仅供内部使用

类型参数 ​

_ExtractGettersFromSetupStore_Keys ​

Ƭ _ExtractGettersFromSetupStore_Keys<SS>: keyof { [K in keyof SS as SS[K] extends ComputedRef ? K : never]: any }

能够通过 IDE 进行重构的类型。 仅供内部使用

类型参数 ​

_ExtractStateFromSetupStore ​

Ƭ _ExtractStateFromSetupStore<SS>: SS extends undefined | void ? {} : _ExtractStateFromSetupStore_Keys<SS> extends keyof SS ? _UnwrapAll<Pick<SS, _ExtractStateFromSetupStore_Keys<SS>>> : never

仅供内部使用

类型参数 ​

_ExtractStateFromSetupStore_Keys ​

Ƭ _ExtractStateFromSetupStore_Keys<SS>: keyof { [K in keyof SS as SS[K] extends _Method | ComputedRef ? never : K]: any }

能够通过 IDE 进行重构的类型。 仅供内部使用

类型参数 ​

_GettersTree ​

Ƭ _GettersTree<S>: Record<string, (state: UnwrapRef<S> & UnwrapRef<PiniaCustomStateProperties<S>>) => any | () => any>

推断参数的 Getter 对象的类型。仅供内部使用。 仅供内部使用

类型参数 ​

_MapActionsObjectReturn ​

Ƭ _MapActionsObjectReturn<A, T>: { [key in keyof T]: A[T[key]] }

仅供内部使用

类型参数 ​

_MapActionsReturn ​

Ƭ _MapActionsReturn<A>: { [key in keyof A]: A[key] }

仅供内部使用

类型参数 ​

_MapStateObjectReturn ​

Ƭ _MapStateObjectReturn<Id, S, G, A, T>: { [key in keyof T]: Function }

仅供内部使用

类型参数 ​

_MapStateReturn ​

Ƭ _MapStateReturn<S, G, Keys>: { [key in Keys]: Function }

仅供内部使用

类型参数 ​

_MapWritableStateObjectReturn ​

Ƭ _MapWritableStateObjectReturn<S, T>: { [key in keyof T]: Object }

仅供内部使用

类型参数 ​

_MapWritableStateReturn ​

Ƭ _MapWritableStateReturn<S>: { [key in keyof S]: Object }

仅供内部使用

类型参数 ​

_Method ​

Ƭ _Method: (...args: any[]) => any

类型声明 ​

▸ (...args): any

可以推断参数和返回值类型的函数通用类型。

仅供内部使用

参数 ​

返回值 ​

any

_Spread ​

Ƭ _Spread<A>: A extends [infer L, ...(infer R)] ? _StoreObject<L> & _Spread<R> : unknown

仅供内部使用.

类型参数 ​

_StoreObject ​

Ƭ _StoreObject<S>: S extends StoreDefinition<infer Ids, infer State, infer Getters, infer Actions> ? { [Id in `${Ids}${MapStoresCustomization extends Record<"suffix", string> ? MapStoresCustomization["suffix"] : "Store"}`]: Function } : {}

仅供内部使用.

类型参数 ​

_StoreWithActions ​

Ƭ _StoreWithActions<A>: { [k in keyof A]: A[k] extends Function ? Function : never }

为 action 增强的 Store。仅供内部使用。 仅供内部使用

类型参数 ​

_StoreWithGetters ​

Ƭ _StoreWithGetters<G>: { readonly [k in keyof G]: G[k] extends Function ? R : UnwrapRef<G[k]> }

Store augmented with getters. For internal usage only. 仅供内部使用

类型参数 ​

_UnwrapAll ​

Ƭ _UnwrapAll<SS>: { [K in keyof SS]: UnwrapRef<SS[K]> }

能够通过 IDE 进行重构的类型。 仅供内部使用

类型参数 ​

变量 ​

PiniaVuePlugin ​

• PiniaVuePlugin: Plugin

Vue 2 插件，必须安装该插件才能使 pinia 工作。 注意，如果你使用的是 Nuxt.js，那你不需要这个插件。请使用 buildModule 代替： https://pinia.vuejs.org/zh/ssr/nuxt.html

Example

import Vue from 'vue'
import { PiniaVuePlugin, createPinia } from 'pinia'

Vue.use(PiniaVuePlugin)
const pinia = createPinia()

new Vue({
  el: '#app',
  // ...
  pinia,
})

import Vue from 'vue'
import { PiniaVuePlugin, createPinia } from 'pinia'

Vue.use(PiniaVuePlugin)
const pinia = createPinia()

new Vue({
  el: '#app',
  // ...
  pinia,
})

param

从 'vue' 导入的 Vue。

函数 ​

acceptHMRUpdate ​

▸ acceptHMRUpdate(initialUseStore, hot): (newModule: any) => any

创建一个 accept 函数，在 Vite 应用中传递给 import.meta.hot。

Example

const useUser = defineStore(...)
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUser, import.meta.hot))
}

const useUser = defineStore(...)
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUser, import.meta.hot))
}

参数 ​

返回值 ​

fn

▸ (newModule): any

参数 ​

返回值 ​

any

createPinia ​

▸ createPinia(): Pinia

创建一个 Pinia 实例，供应用使用。

返回值 ​

Pinia

defineStore ​

▸ defineStore<Id, S, G, A>(id, options): StoreDefinition<Id, S, G, A>

创建一个 useStore 函数，检索 store 实例

类型参数 ​

参数 ​

返回值 ​

StoreDefinition<Id, S, G, A>

▸ defineStore<Id, S, G, A>(options): StoreDefinition<Id, S, G, A>

创建一个 useStore 函数，检索 store 实例

类型参数 ​

参数 ​

返回值 ​

StoreDefinition<Id, S, G, A>

▸ defineStore<Id, SS>(id, storeSetup, options?): StoreDefinition<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>

创建一个 useStore 函数，检索 store 实例

类型参数 ​

参数 ​

返回值 ​

StoreDefinition<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>

getActivePinia ​

▸ getActivePinia(): undefined | Pinia

如果有的话，获取当前激活的 pinia

返回值 ​

undefined | Pinia

mapActions ​

▸ mapActions<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapActionsObjectReturn<A, KeyMapper>

通过生成一个传递到组件的 methods 字段的对象， 允许直接使用 store 的 action，而不需要使用组合式 API(setup())。 该对象的值是 action， 而键是产生的方法名称。

Example

export default {
  methods: {
    // 其他方法属性
    // useCounterStore 有两个 action，分别是 `increment` 与 `setCount`。
    ...mapActions(useCounterStore, { moar: 'increment', setIt: 'setCount' })
  },

  created() {
    this.moar()
    this.setIt(2)
  }
}

export default {
  methods: {
    // 其他方法属性
    // useCounterStore 有两个 action，分别是 `increment` 与 `setCount`。
    ...mapActions(useCounterStore, { moar: 'increment', setIt: 'setCount' })
  },

  created() {
    this.moar()
    this.setIt(2)
  }
}

类型参数 ​

参数 ​

返回值 ​

_MapActionsObjectReturn<A, KeyMapper>

▸ mapActions<Id, S, G, A>(useStore, keys): _MapActionsReturn<A>

允许直接使用 store 里的 action， 而不是必须使用组合式 API(setup())， 通过生成一个对象，传递到组件的 methods 字段。

Example

export default {
  methods: {
    // 其他方法属性
    ...mapActions(useCounterStore, ['increment', 'setCount'])
  },

  created() {
    this.increment()
    this.setCount(2) // 像往常一样传递参数
  }
}

export default {
  methods: {
    // 其他方法属性
    ...mapActions(useCounterStore, ['increment', 'setCount'])
  },

  created() {
    this.increment()
    this.setCount(2) // 像往常一样传递参数
  }
}

类型参数 ​

参数 ​

返回值 ​

_MapActionsReturn<A>

mapGetters ​

▸ mapGetters<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapStateObjectReturn<Id, S, G, A, KeyMapper>

通过生成一个对象传递到组件的 computed 字段中。 允许使用来自一个 store 的 state 和 getter，而不必使用组合式 API(setup())。 该对象的值是 state 属性/ getter 而键则是产生的计算属性的名称。 另外，你还可以传递一个自定义函数， 该函数将接收 state 的作为其第一个参数。 注意，虽然它可以通过 this 访问组件的实例，但它没有标注类型。

Example

export default {
  computed: {
    // 其他计算属性
    // useCounterStore 有一个名为 `count` 的 state 属性以及一个名为 `double` 的 getter
    ...mapState(useCounterStore, {
      n: 'count',
      triple: store => store.n * 3,
      // 注意如果你想要使用 `this`，那你不能使用箭头函数
      custom(store) {
        return this.someComponentValue + store.n
      },
      doubleN: 'double'
    })
  },

  created() {
    this.n // 2
    this.doubleN // 4
  }
}

export default {
  computed: {
    // 其他计算属性
    // useCounterStore 有一个名为 `count` 的 state 属性以及一个名为 `double` 的 getter
    ...mapState(useCounterStore, {
      n: 'count',
      triple: store => store.n * 3,
      // 注意如果你想要使用 `this`，那你不能使用箭头函数
      custom(store) {
        return this.someComponentValue + store.n
      },
      doubleN: 'double'
    })
  },

  created() {
    this.n // 2
    this.doubleN // 4
  }
}

类型参数 ​

参数 ​

返回值 ​

_MapStateObjectReturn<Id, S, G, A, KeyMapper>

▸ mapGetters<Id, S, G, A, Keys>(useStore, keys): _MapStateReturn<S, G, Keys>

通过生成一个对象传递到组件的 computed 字段中， 以允许使用来自一个 store 的 state 和 getter， 而不必使用组合式 API(setup())，

Example

export default {
  computed: {
    // 其他计算属性
    ...mapState(useCounterStore, ['count', 'double'])
  },

  created() {
    this.count // 2
    this.double // 4
  }
}

export default {
  computed: {
    // 其他计算属性
    ...mapState(useCounterStore, ['count', 'double'])
  },

  created() {
    this.count // 2
    this.double // 4
  }
}

类型参数 ​

参数 ​

返回值 ​

_MapStateReturn<S, G, Keys>

mapState ​

▸ mapState<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapStateObjectReturn<Id, S, G, A, KeyMapper>

通过生成一个对象，并传递至组件的 computed 字段， 以允许在不使用组合式 API(setup())的情况下使用一个 store 的 state 和 getter。 该对象的值是 state 属性/getter， 而键是生成的计算属性名称。 你也可以选择传递一个自定义函数，该函数将接收 store 作为其第一个参数。 注意，虽然它可以通过 this 访问组件实例，但它没有标注类型。

Example

export default {
  computed: {
    // 其他计算属性
    // useCounterStore 拥有一个名为 `count` 的 state 属性和一个名为 `double` 的 getter
    ...mapState(useCounterStore, {
      n: 'count',
      triple: store => store.n * 3,
      // 如果想使用 `this`，就不能使用箭头函数
      custom(store) {
        return this.someComponentValue + store.n
      },
      doubleN: 'double'
    })
  },

  created() {
    this.n // 2
    this.doubleN // 4
  }
}

export default {
  computed: {
    // 其他计算属性
    // useCounterStore 拥有一个名为 `count` 的 state 属性和一个名为 `double` 的 getter
    ...mapState(useCounterStore, {
      n: 'count',
      triple: store => store.n * 3,
      // 如果想使用 `this`，就不能使用箭头函数
      custom(store) {
        return this.someComponentValue + store.n
      },
      doubleN: 'double'
    })
  },

  created() {
    this.n // 2
    this.doubleN // 4
  }
}

类型参数 ​

参数 ​

返回值 ​

_MapStateObjectReturn<Id, S, G, A, KeyMapper>

▸ mapState<Id, S, G, A, Keys>(useStore, keys): _MapStateReturn<S, G, Keys>

通过生成一个对象，并传递到组件的 computed 字段， 允许在不使用组合式 API(setup())的情况下 使用一个 store 的 state 和 getter，

Example

export default {
  computed: {
    // 其他计算属性
    ...mapState(useCounterStore, ['count', 'double'])
  },

  created() {
    this.count // 2
    this.double // 4
  }
}

export default {
  computed: {
    // 其他计算属性
    ...mapState(useCounterStore, ['count', 'double'])
  },

  created() {
    this.count // 2
    this.double // 4
  }
}

类型参数 ​

参数 ​

返回值 ​

_MapStateReturn<S, G, Keys>

mapStores ​

▸ mapStores<Stores>(...stores): _Spread<Stores>

通过生成一个对象，传递到组件的 computed 字段 以允许在不使用组合式 API(setup())的情况下使用 store。 它接受一个 store 定义的列表参数。

Example

export default {
  computed: {
    // 其他计算属性
    ...mapStores(useUserStore, useCartStore)
  },

  created() {
    this.userStore // id 为 "user" 的 store
    this.cartStore // id 为 "cart" 的 store
  }
}

export default {
  computed: {
    // 其他计算属性
    ...mapStores(useUserStore, useCartStore)
  },

  created() {
    this.userStore // id 为 "user" 的 store
    this.cartStore // id 为 "cart" 的 store
  }
}

类型参数 ​

参数 ​

返回值 ​

_Spread<Stores>

mapWritableState ​

▸ mapWritableState<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapWritableStateObjectReturn<S, KeyMapper>

除了创建的计算属性的 setter，其他与 mapState() 相同， 所以 state 可以被修改。 与 mapState() 不同的是，只有 state 属性可以被添加。

类型参数 ​

参数 ​

返回值 ​

_MapWritableStateObjectReturn<S, KeyMapper>

▸ mapWritableState<Id, S, G, A>(useStore, keys): _MapWritableStateReturn<S>

通过生成一个对象并传递到组件的 computed 字段 以允许在不使用组合式 API(setup())的情况下 使用来自一个 store 的 state 和 getter，。

类型参数 ​

参数 ​

返回值 ​

_MapWritableStateReturn<S>

setActivePinia ​

▸ setActivePinia(pinia): undefined | Pinia

设置或取消设置激活的 pinia。 在 SSR 和内部调用 action 和 getter 时使用。

参数 ​

返回值 ​

undefined | Pinia

setMapStoreSuffix ​

▸ setMapStoreSuffix(suffix): void

改变由 mapStores() 添加的后缀。可以设置为空字符串。 默认为"Store"。如果你需要使用 TypeScript， 请确保扩展 MapStoresCustomization 接口。

参数 ​

返回值 ​

void

skipHydrate ​

▸ skipHydrate<T>(obj): T

告诉 Pinia 跳过给定对象的激活过程。当你在 store 中返回一个有状态的对象，但它并不是真正的状态时，(仅)在 setup store 中这是很有用的。 例如，在一个 setup store 中返回一个路由器实例。

类型参数 ​

参数 ​

返回值 ​

T

obj

storeToRefs ​

▸ storeToRefs<SS>(store): ToRefs<StoreState<SS> & StoreGetters<SS> & PiniaCustomStateProperties<StoreState<SS>>>

创建一个引用对象，包含 store 的所有 state、 getter 和 plugin 添加的 state 属性。 类似于 toRefs()，但专门为 Pinia store 设计， 所以 method 和非响应式属性会被完全忽略。

类型参数 ​

参数 ​

返回值 ​

ToRefs<StoreState<SS> & StoreGetters<SS> & PiniaCustomStateProperties<StoreState<SS>>>