Pinia 持久化存储插件 pinia-plugin-persist 介绍及源码解读

什么是 Pinia ？

Pinia 出来这么久了（2019年11月左右），也有很多的质量非常不错的文章讲解关于 Pinia 的基本使用方式，这里就不再赘述了。

一句话总结一下：

方便追踪与调试 state，支持 Composition API 定义 store，支持 HMR，支持 Plugin 扩展

其核心的 defineStore API，让我觉得它可以摒弃之前 Vuex 的全局集中状态管理的思想，利用 Vue 3 的 Composition 特性，提供随处按需定义小型 store 的能力。

这让我们更加容易编写和管理很多不同模块的 store，提高代码可读性，也让 store 更容易的扩展。

如何持久化？

在某些特定的单页面应用场景下，我们使用常规的 store 来存储数据，很多时候面临着刷新就会被重置，所以，我们急需一个插件功能来实现对某些特定的数据进行状态保持。

这里我们很容易想到可以用 sessionStorage 或者 localStorage 来进行相应的处理，但是要对不同的 store 中不同的字段进行处理，也是有很大的心智负担。

这里我推荐一款 Pinia 的持久化插件：pinia-plugin-persist

他提供了简便的使用方式以及灵活的配置方式，下面我就和大家分享一下这款插件的使用方式及实现原理。

使用方法

install

# npm
npm install pinia-plugin-persist

# yarn
yarn add pinia-plugin-persist

# pnpm
pnpm add pinia-plugin-persist

setup

Vue 2

import Vue from 'vue'
import vueCompositionApi from '@vue/composition-api'
import { createPinia } from 'pinia'
import piniaPersist from 'pinia-plugin-persist'

const pinia = createPinia()
pinia.use(piniaPersist)

Vue.use(vueCompositionApi)
Vue.use(pinia)

Vue 3

import { createPinia } from 'pinia'
import piniaPersist from 'pinia-plugin-persist'

const pinia = createPinia()
pinia.use(piniaPersist)

Typescript definitions

// tsconfig.ts
{
  "compilerOptions": {
    "types": [
      "pinia-plugin-persist"
    ]
  },
}

Usage

源码即文档

export interface PersistStrategy {
    key?: string;
    storage?: Storage;
    paths?: string[];
}
export interface PersistOptions {
    enabled: true;
    strategies?: PersistStrategy[];
}
declare type Store = PiniaPluginContext['store'];
declare module 'pinia' {
    interface DefineStoreOptionsBase<S, Store> {
        persist?: PersistOptions;
    }
}

1. 基本使用

import { defineStore } from "pinia"

export const useStore = defineStore("YourStore", () => {
    const foo = ref("foo")
    const bar = ref("bar")
    return { foo, bar }
}, {
    enabled: true
})

开启 enabled 之后，默认会对整个 Store 的 state 内容进行 sessionStorage 储存。

2. 进阶用法

strategies 字段说明：

属性	描述
key	自定义存储的 key，默认是 store.$id
storage	可以指定任何 extends Storage 的实例，默认是 sessionStorage
paths	state 中的字段名，按组打包储存

import { defineStore } from "pinia"

export const useStore = defineStore("YourStore", () => {
    const foo = ref("foo")
    const bar = ref("bar")
    return { foo, bar }
}, {
    enabled: true,
    strategies: [{
        // 自定义存储的 key，默认是 store.$id
        key: "custom storageKey",
        // 可以指定任何 extends Storage 的实例，默认是 sessionStorage
        storage: localStorage,
        // state 中的字段名，按组打包储存
        paths: ["foo", "bar"]
    }]
})

storage 属性可以使用任何继承自 Storage 协议的对象，自定义存储对象也可以，如下 cookiesStorage 为例

import Cookies from 'js-cookie'

const cookiesStorage: Storage = {
  setItem (key, state) {
    return Cookies.set('accessToken', state.accessToken, { expires: 3 })
  },
  getItem (key) {
    return JSON.stringify({
      accessToken: Cookies.getJSON('accessToken'),
    })
  },
}

export const useStore = defineStore("YourStore", () => {
    const foo = ref("foo")
    const bar = ref("bar")
    const accessToken = ref("xxx")
    return { foo, bar, accessToken }
}, {
    enabled: true,
    strategies: [{
        key: "token",
        storage: cookiesStorage,
        paths: ["accessToken"]
    }]
})

源码解读

type Store = PiniaPluginContext['store'];
type PartialState = Partial<Store['$state']>;

export const updateStorage = (strategy: PersistStrategy, store: Store) => {

  // 默认使用 sessionStorage
  const storage = strategy.storage || sessionStorage
  
  // 默认存储 key 为 store.$id
  const storeKey = strategy.key || store.$id

  if (strategy.paths) {
  
    // 遍历 paths 将对应的属性收集到 finalObj 中
    const partialState = strategy.paths.reduce((finalObj, key) => {
      finalObj[key] = store.$state[key]
      return finalObj
    }, {} as PartialState)
    
    // 执行存储
    storage.setItem(storeKey, JSON.stringify(partialState))
  } else {
  
    // 如果没有 paths，则按整个 store.$state 存储
    storage.setItem(storeKey, JSON.stringify(store.$state))
  }
}


export default ({ options, store }: PiniaPluginContext): void => {

  // 判断插件功能是否开启
  if (options.persist?.enabled) {
  
    // 默认策略实例
    const defaultStrat: PersistStrategy[] = [{
      key: store.$id,
      storage: sessionStorage,
    }]

    const strategies = options.persist?.strategies?.length ? options.persist?.strategies : defaultStrat

    strategies.forEach((strategy) => {
      const storage = strategy.storage || sessionStorage
      const storeKey = strategy.key || store.$id
      const storageResult = storage.getItem(storeKey)

      if (storageResult) {
      
        // 如果 storage 中存在同步数据
        store.$patch(JSON.parse(storageResult))
        updateStorage(strategy, store)
      }
    })

    store.$subscribe(() => {
    
      // 监听 state 变化，同步更新 storage
      strategies.forEach((strategy) => {
        updateStorage(strategy, store)
      })
    })
  }
}

看完源码之后，发现功能其实很简单，但是其中灵活的 API 设计还是让我眼前一亮，扩展性和定制性也得到了的极大的提升，还是非常值得学习的一个插件。

最后

有了持久化存储的能力，我们就可以更愉快的进行数据管理啦~