x-pinia-s

Pinia v3.0.4 单文件版 + 基于 uni 存储的持久化插件。去掉 @vue/devtools-api 依赖，适配 uni-app-x；自带 createPersistPlugin，用 uni.setStorageSync 保存 store.$state，下次启动自动还原。

兼容性

Harmony	IOS	Android	WEB	小程序
支持	支持	支持	支持	支持

接入

main.uts 中创建 Pinia 并挂载持久化插件：

// @ts-ignore
import { createPinia } from '@/uni_modules/x-pinia-s/js_sdk/pinia'
import { createPersistPlugin } from '@/uni_modules/x-pinia-s/js_sdk/piniaPersist'

const pinia = createPinia()

export function createApp() {
  // @ts-ignore
  const app = createSSRApp(App)

  pinia.use(createPersistPlugin({
    keyPrefix: 'pinia:',
    includeStores: ['user'],
    excludeStores: [],
    serializer: null
  }))
  app.use(pinia)

  return {
    app
  }
}

定义 store

import { ref, computed } from 'vue'
// @ts-ignore
import { defineStore } from '@/uni_modules/x-pinia-s/js_sdk/pinia'

export const useUserStore = defineStore('user', () => {
  const token = ref<string | null>(null)
  const isLogin = computed(() : boolean => token.value != null && token.value != '')

  const setLogin = (newToken : string) => {
    token.value = newToken
  }

  return {
    token,
    isLogin,
    setLogin
  }
})

页面中使用：

import { useUserStore } from '@/store/useUserStore'
import { storeToRefs } from '@/uni_modules/x-pinia-s/js_sdk/pinia'

const store = useUserStore()
const { token } = storeToRefs(store)
store.setLogin('abc')

方法

名称	说明
createPinia	创建 Pinia 实例
defineStore	定义 store，支持 options 与 setup 两种写法
storeToRefs	解构 state / getters 并保持响应式
mapState / mapActions / mapStores / mapWritableState	Options API 辅助函数
acceptHMRUpdate	HMR 更新
setActivePinia / getActivePinia	SSR 或组件外手动切换活动实例
disposePinia	销毁 Pinia 实例
skipHydrate / shouldHydrate	控制 setup store 的 hydration
createPersistPlugin	持久化插件
clearPersistedState	清除某个 store 的持久化数据

持久化插件参数

createPersistPlugin(options)

字段	说明	默认
keyPrefix	storage key 前缀，实际 key 为 keyPrefix + store.$id	pinia:
includeStores	白名单，null 表示全部持久化	null
excludeStores	黑名单，优先级高于白名单	[]
serializer	自定义序列化器 { serialize, deserialize }，null 用 JSON	null

import { clearPersistedState } from '@/uni_modules/x-pinia-s/js_sdk/piniaPersist'

// 只清存储，不影响内存状态
clearPersistedState('user', 'pinia:')

平台差异

1. 单文件接入，去掉 @vue/devtools-api，uni-app-x 无 Vue DevTools。
2. 持久化走 uni.setStorageSync / uni.getStorageSync，各端存储实现由 uni 提供。
3. 白名单 / 黑名单按 store.$id 匹配；同时命中时黑名单优先。

版本

https://xui.tmui.design 下载归档。

更新日志

1.0.0（2026-08-24）

• 接入 Pinia v3.0.4，单文件编译，去掉 @vue/devtools-api，适配 uni-app-x
• 提供 createPersistPlugin 持久化插件，uni.setStorageSync 保存 store.$state，启动自动还原
• 提供 clearPersistedState 清除单个 store 的持久化数据