从 0.x (v1) 迁移至 v2

2.0.0-rc.4 版本开始,pinia 同时支持 Vue 2 和 Vue 3!这意味着,v2 版本的所有更新,将会让 Vue 2 和 Vue 3 的用户都受益。如果你使用的是 Vue 3,这对你来说没有任何改变,因为你已经在使用 rc 版本,你可以查看发布日志来了解所有更新的详细解释。如果你使用的不是 Vue 3,那这个指南是为你准备的!

弃用

让我们来看看你需要对你的代码做出的所有修改。首先,为了解所有弃用,确保你已经在运行最新的 0.x 版本:

npm i 'pinia@^0.x.x'
# 或者使用 yarn
yarn add 'pinia@^0.x.x'

如果你正在使用 ESLint,可以考虑使用这个插件,来查找所有废弃的用法。否则,你得手动检查。这些都是被废弃且已经删除了的 API:

  • createStore() 变成 defineStore()
  • 在订阅中,storeName 变成 storeId
  • PiniaPlugin 更名为 PiniaVuePlugin(Vue 2 的 Pinia 插件)
  • $subscribe() 不再接受 boolean 作为第二个参数,而是传递一个带有 detached: true 的对象。
  • Pinia 插件不再直接接收 store 的 id。使用 store.$id 代替。

非兼容性更新

删除下面这些后,你可以用下面命令升级到 V2 版了:

npm i 'pinia@^2.x.x'
# 或者使用 yarn
yarn add 'pinia@^2.x.x'

然后开始更新你的代码。

通用 Store 类型

添加于 2.0.0-rc.0

StoreGeneric 取代 GenericStore 类型的全部用法。这是新的通用 store 类型,应该可以接受任何类型的 store。如果你在写函数时使用 Store 类型而不想传递其泛型(例如Store<Id, State, Getters, Actions>),你可以使用 StoreGeneric,因为没有泛型的 Store 类型会创建一个空的 store 类型:

-function takeAnyStore(store: Store) {}
+function takeAnyStore(store: StoreGeneric) {}

-function takeAnyStore(store: GenericStore) {}
+function takeAnyStore(store: StoreGeneric) {}

针对插件的 DefineStoreOptions

如果你在用 TypeScript 写插件并扩展了 DefineStoreOptions 类型来添加自定义选项,你应该把它改名为 DefineStoreOptionsBase。这个类型将同时适用于 setup 和 option store。

 declare module 'pinia' {
-  export interface DefineStoreOptions<S, Store> {
+  export interface DefineStoreOptionsBase<S, Store> {
     debounce?: {
       [k in keyof StoreActions<Store>]?: number
     }
   }
 }

PiniaStorePlugin已被重命名

类型 PiniaStorePlugin 被重新命名为 PiniaPlugin

-import { PiniaStorePlugin } from 'pinia'
+import { PiniaPlugin } from 'pinia'

-const piniaPlugin: PiniaStorePlugin = () => {
+const piniaPlugin: PiniaPlugin = () => {
   // ...
 }

注意这个更新只能在升级到最新的没有弃用的 Pinia 版本后生效

@vue/composition-api版本

由于 pinia 目前依赖于 effectScope() ,你使用的 @vue/composition-api 的版本必须是 1.1.0 及以上:

npm i @vue/composition-api@latest
# 或者使用 yarn
yarn add @vue/composition-api@latest

支持 webpack 4

如果你使用的是 webpack 4(Vue CLI 使用的是 webpack 4),你可能会遇到这样的错误:

ERROR  Failed to compile with 18 errors

 error  in ./node_modules/pinia/dist/pinia.mjs

Can't import the named export 'computed' from non EcmaScript module (only default export is available)

这是构建文件为支持 Node.js 中的原生 ESM 模块进行的现代化适配。为更好地支持 Node,文件现在使用的扩展名是 .mjs.cjs。要解决这个问题,你有两种可用的方法:

  • 如果你使用 Vue CLI 4.x,升级你的依赖。具体修复步骤如下。
    • 如果你不可能升级,请将下面的代码添加到你的 vue.config.js 中:
      // vue.config.js
      module.exports = {
        configureWebpack: {
          module: {
            rules: [
              {
                test: /\.mjs$/,
                include: /node_modules/,
                type: 'javascript/auto',
              },
            ],
          },
        },
      }
      
  • 如果你手动处理 webpack,你将必须让它知道如何处理 .mjs 文件:
    // webpack.config.js
    module.exports = {
      module: {
        rules: [
          {
            test: /\.mjs$/,
            include: /node_modules/,
            type: 'javascript/auto',
          },
        ],
      },
    }
    

Devtools

Pinia v2 不再劫持 Vue Devtools v5,它需要的是 Vue Devtools v6。可以在 Vue Devtools 文档中找到该扩展 beta 版本的下载链接。

Nuxt

如果你正在使用 Nuxt,pinia 现在有了专门的 Nuxt 软件包🎉。请用以下方法安装它:

npm i @pinia/nuxt
# 或者使用 yarn
yarn add @pinia/nuxt

还要确保更新你的 @nuxtjs/composition-api

如果你使用 TypeScript,还要调整你的 nuxt.config.jstsconfig.json

 // nuxt.config.js
 module.exports {
   buildModules: [
     '@nuxtjs/composition-api/module',
-    'pinia/nuxt',
+    '@pinia/nuxt',
   ],
 }
 // tsconfig.json
 {
   "types": [
     // ...
-    "pinia/nuxt/types"
+    "@pinia/nuxt"
   ]
 }

Nuxt 专署章节也值得一读。