Plugins

Plugins

由于低版本的API，Pinia的stores可以完全扩展。下面是一些你可以做的事情:

向stores添加新的属性
在定义stores时添加新选项
向stores添加新方法
包装现有的方法
更改甚至取消操作
实现像本地存储这样的功能
只适用于特定的stores

使用pinia.use()将插件添加到pinia实例中。最简单的例子是通过返回一个对象向所有stores 添加一个静态属性:

import { createPinia } from 'pinia'
// add a property named `secret` to every store that is created after this plugin is installed
// this could be in a different file
function SecretPiniaPlugin() {
  return { secret: 'the cake is a lie' }
}
const pinia = createPinia()
// give the plugin to pinia
pinia.use(SecretPiniaPlugin)
// in another file
const store = useStore()
store.secret // 'the cake is a lie'

这对于添加全局对象（如router、modal或toast管理器）非常有用。

介绍

Pinia的插件是一个函数，可以选择返回要添加到store中的属性。它有一个可选参数 context:

export function myPiniaPlugin(context) {
  context.pinia // the pinia created with `createPinia()`
  context.app // the current app created with `createApp()` (Vue 3 only)
  context.store // the store the plugin is augmenting
  context.options // the options object defining the store passed to `defineStore()`
  // ...
}

然后将此函数传递给pinia的pinia.use()：

pinia.use(myPiniaPlugin)

插件只应用于stores被创建在pinia传递给应用程序后，否则它们不会被应用。

扩展 Store

你可以通过在插件中返回一个属性对象来为每个store添加属性:

pinia.use(() => ({ hello: 'world' }))

你也可以直接在store中设置属性，如果可以的话，请返回版本，以便它们可以被devtools自动跟踪：

pinia.use(({ store }) => {
  store.hello = 'world'
})

插件返回的任何属性都将由devtools自动追踪，因此为了hello在devtools中可见，请确保仅在开发模式中添加store._customProperties属性，如果您想在devtools中调试的话：

// from the example above
pinia.use(({ store }) => {
  store.hello = 'world'
  // make sure your bundler handle this. webpack and vite should do it by default
  if (process.env.NODE_ENV === 'development') {
    // add any keys you set on the store
    store._customProperties.add('hello')
  }
})

需要注意的是，每个store都会使用reactive包装，并且会自动解包它包含的任何Ref(ref(), computed(), …）等：

const sharedRef = ref('shared')
pinia.use(({ store }) => {
  // each store has its individual `hello` property
  store.hello = ref('secret')
  // it gets automatically unwrapped
  store.hello // 'secret'
  // all stores are sharing the value `shared` property
  store.shared = sharedRef
  store.shared // 'shared'
})

这就是为什么您可以访问所有不带.value计算属性它们是响应式的原因。

添加新状态

如果您想在激活过程中添加新的状态属性或属性到store，您必须在两个地方添加它：

在store中，您可以通过store.myState访问它
在store.$state中，它可以在devtools中使用，并且在SSR期间被序列化。

请注意，这允许您共享ref或computed属性：

const globalSecret = ref('secret')
pinia.use(({ store }) => {
  // `secret` is shared among all stores
  store.$state.secret = globalSecret
  store.secret = globalSecret
  // it gets automatically unwrapped
  store.secret // 'secret'
  const hasError = ref(false)
  store.$state.hasError = hasError
  // this one must always be set
  store.hasError = toRef(store.$state, 'hasError')
  // in this case it's better not to return `hasError` since it
  // will be displayed in the `state` section in the devtools
  // anyway and if we return it, devtools will display it twice.
})

请注意，在插件中发生的状态改变或添加（包括调用store.$patch()）发生在store激活之前，因此不会触发任何订阅。

WARNING 如果您使用的是Vue 2，Pinia将受到与Vue相同的反应警告。当创建新的状态属性如 secret和hasError时，您需要使用来自@vue/composition-api的set方法。

import { set } from '@vue/composition-api'
pinia.use(({ store }) => {
  if (!store.$state.hasOwnProperty('hello')) {
    const secretRef = ref('secret')
    // If the data is meant to be used during SSR, you should
    // set it on the `$state` property so it is serialized and
    // picked up during hydration
    set(store.$state, 'secret', secretRef)
    // set it directly on the store too so you can access it
    // both ways: `store.$state.secret` / `store.secret`
    set(store, 'secret', secretRef)
    store.secret // 'secret'
  }
})

添加新的外部属性

当添加外部属性，来自其他库的类实例或简单的非响应式对象时，应该在将对象传递给pinia 之前使用markRaw()包装该对象。下面是一个将路由添加到所有store的示例:

import { markRaw } from 'vue'
// adapt this based on where your router is
import { router } from './router'
pinia.use(({ store }) => {
  store.router = markRaw(router)
})

在插件内部调用 $subscribe

您也可以在插件中使用store.$subscribe和store.$onAction:

pinia.use(({ store }) => {
  store.$subscribe(() => {
    // react to store changes
  })
  store.$onAction(() => {
    // react to store actions
  })
})

添加新选项

可以在定义stores时创建新的选项，以便随后从插件中使用它们。例如，你可以创建一个debounce选项，允许你对任何操作进行debounce :

defineStore('search', {
  actions: {
    searchContacts() {
      // ...
    },
  },
  // this will be read by a plugin later on
  debounce: {
    // debounce the action searchContacts by 300ms
    searchContacts: 300,
  },
})

插件可以读取该选项来包装actions并替换原来的actions:

// use any debounce library
import debounce from 'lodash/debunce'
pinia.use(({ options, store }) => {
  if (options.debounce) {
    // we are overriding the actions with new ones
    return Object.keys(options.debounce).reduce((debouncedActions, action) => {
      debouncedActions[action] = debounce(
        store[action],
        options.debounce[action]
      )
      return debouncedActions
    }, {})
  }
})

请注意，使用setup语法时，自定义选项作为第三个参数传入：

defineStore(
  'search',
  () => {
    // ...
  },
  {
    // this will be read by a plugin later on
    debounce: {
      // debounce the action searchContacts by 300ms
      searchContacts: 300,
    },
  }
)

TypeScript

上面显示的所有内容都可以通过编写支持，因此您无需使用any或@ts-ignore。

编写插件

Pinia插件可以按如下方式编写：

import { PiniaPluginContext } from 'pinia'
export function myPiniaPlugin(context: PiniaPluginContext) {
  // ...
}

编写新的store属性

当向stores添加新属性时，您还应该扩展PiniaCustomProperties接口。

import 'pinia'
declare module 'pinia' {
  export interface PiniaCustomProperties {
    // by using a setter we can allow both strings and refs
    set hello(value: string | Ref<string>)
    get hello(): string
    // you can define simpler values too
    simpleNumber: number
  }
}

然后可以安全地写入和读取：

pinia.use(({ store }) => {
  store.hello = 'Hola'
  store.hello = ref('Hola')
  store.number = Math.random()
  // @ts-expect-error: we haven't typed this correctly
  store.number = ref(Math.random())
})

PiniaCustomProperties是一个泛型类型，允许您引用store的属性。想象一下下面的示例，我们将初始选项复制为$options（这仅适用于option stores）：

pinia.use(({ options }) => ({ $options: options }))

我们可以通过使用PiniaCustomProperties的4个泛型类型来正确地输入这个值:

import 'pinia'
declare module 'pinia' {
  export interface PiniaCustomProperties<Id, S, G, A> {
    $options: {
      id: Id
      state?: () => S
      getters?: G
      actions?: A
    }
  }
}

TIP

在泛型中扩展类型时，它们的命名必须与源码中的完全相同。Id不能命名为id或I，S也不能命名为State。以下是每个字母所代表的含义：

S: State
G: Getters
A: Actions
SS: Setup Store / Store

编写新的状态

当添加新的状态属性时(同时添加到store和store.$state)，您需要将类型添加到PiniaCustomStateProperties。与PiniaCustomProperties不同的是，它只接收State泛型：

import 'pinia'
declare module 'pinia' {
  export interface PiniaCustomStateProperties<S> {
    hello: string
  }
}

编写新的创建选项

当为defineStore()创建新选项时，您应该扩展DefineStoreOptionsBase。与PiniaCustomProperties不同的是，它只公开两种泛型：State和Store类型，允许您限制可以定义的类型。例如，你可以使用actions的名称:

import 'pinia'
declare module 'pinia' {
  export interface DefineStoreOptionsBase<S, Store> {
    // allow defining a number of ms for any of the actions
    debounce?: Partial<Record<keyof StoreActions<Store>, number>>
  }
}

TIP 还有一个StoreGetters类型用于从Store类型中提取getters。您还可以分别通过DefineStoreOptions和DefineSetupStoreOptions类型来扩展设置setup stores或option stores的选项。

Nuxt.js

当Nuxt和Pinia一起使用时，您必须先创建一个Nuxt插件。这将使您可以访问该Pinia实例：

// plugins/myPiniaPlugin.js
import { PiniaPluginContext } from 'pinia'
import { Plugin } from '@nuxt/types'
function MyPiniaPlugin({ store }: PiniaPluginContext) {
  store.$subscribe((mutation) => {
    // react to store changes
    console.log(`[🍍 ${mutation.storeId}]: ${mutation.type}.`)
  })
  return { creationTime: new Date() }
}
const myPlugin: Plugin = ({ pinia }) {
  pinia.use(MyPiniaPlugin);
}
export default myPlugin

注意上面的例子使用的是TypeScript，如果你使用的是.js文件，你必须删除PiniaPluginContext的类型注释和Plugin的引入。