用 VS Code 代码片段快速生成 Pinia Store:Options 与 Setup 双语法脚手架指南
用 VS Code 代码片段快速生成 Pinia Store:Options 与 Setup 双语法脚手架指南
Pinia 是 Vue 官方推荐的轻量级状态管理库,其 Store 定义有 Options 与 Setup 两种语法。本文基于官方文档《VS Code Snippets》整理出一套可直接复制到 VS Code 用户代码片段中的脚手架模板,让你在新建 Store 文件时通过 pinia-options 或 pinia-setup 两个前缀一键生成包含 defineStore、类型安全的 state/getters/actions 以及 HMR 热更新接入的完整骨架。读完本文,你将掌握片段中每个变量的含义、模板与 Pinia 源码(defineStore 与 acceptHMRUpdate)的对应关系,并能按需扩展出自己的 Store 脚手架。
为什么需要 Store 代码片段
在真实项目中,每个 Store 文件都包含大量重复的样板代码:defineStore 的导入、Store id 的声明、state/getters/actions(或 Setup 语法的 return 对象)以及热更新所需的 acceptHMRUpdate 接线。手工逐个输入不仅低效,还容易遗忘 HMR 那段代码,导致开发体验回退到「改一行、刷一页」。
把模板固化到 VS Code 用户代码片段后:
- 输入
pinia-options+Tab即可生成 Options Store 完整骨架; - 输入
pinia-setup+Tab即可生成 Setup Store 完整骨架; - Store 名称根据文件名自动推导(PascalCase),杜绝命名不一致;
- HMR 代码自动附带,
import.meta.hot保护也让模板在非 Vite 环境(如构建产物)下安全执行。
第一步:打开 VS Code 用户代码片段面板
打开命令面板,在 macOS 上按 ⇧ Shift+⌘ Command+P,在 Windows / Linux 上按 ⇧ Shift+⌃ Control+P,然后输入并执行 Snippets: Configure User Snippets。
在弹出的列表中选择 New Global Snippets file...(全局生效)或某个具体语言(如 typescript.json、javascript.json)来限定生效范围。推荐新建一个全局文件(例如 pinia.code-snippets),配合片段内的 scope 字段控制语言范围,这样在任何 Vue 项目中都能复用。
完整片段配置(直接复制即可用)
把下面整个 JSON 内容粘贴到你的用户代码片段文件中(原样继承自官方文档《VS Code Snippets》):
{
"Pinia Options Store Boilerplate": {
"scope": "javascript,typescript",
"prefix": "pinia-options",
"body": [
"import { defineStore, acceptHMRUpdate } from 'pinia'",
"",
"export const use${TM_FILENAME_BASE/^(.*)$/${1:/pascalcase}/}Store = defineStore('$TM_FILENAME_BASE', {",
" state: () => ({",
" $0",
" }),",
" getters: {},",
" actions: {},",
"})",
"",
"if (import.meta.hot) {",
" import.meta.hot.accept(acceptHMRUpdate(use${TM_FILENAME_BASE/^(.*)$/${1:/pascalcase}/}Store, import.meta.hot))",
"}",
""
],
"description": "Bootstrap the code needed for a Vue.js Pinia Options Store file"
},
"Pinia Setup Store Boilerplate": {
"scope": "javascript,typescript",
"prefix": "pinia-setup",
"body": [
"import { defineStore, acceptHMRUpdate } from 'pinia'",
"",
"export const use${TM_FILENAME_BASE/^(.*)$/${1:/pascalcase}/}Store = defineStore('$TM_FILENAME_BASE', () => {",
" $0",
" return {}",
"})",
"",
"if (import.meta.hot) {",
" import.meta.hot.accept(acceptHMRUpdate(use${TM_FILENAME_BASE/^(.*)$/${1:/pascalcase}/}Store, import.meta.hot))",
"}",
""
],
"description": "Bootstrap the code needed for a Vue.js Pinia Setup Store file"
}
}
保存后在任意 .js / .ts 文件中输入 pinia-options 或 pinia-setup 并按下 Tab,即可展开对应模板。
Options Store 片段逐段解析
Options 片段对应 Pinia 的 Option Stores 语法,展开后结构如下:
import { defineStore, acceptHMRUpdate } from 'pinia'
export const useCounterStore = defineStore('counter', {
state: () => ({
$0
}),
getters: {},
actions: {},
})
if (import.meta.hot) {
import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot))
}
要点拆解:
defineStore('$TM_FILENAME_BASE', { ... }):第一个参数是全局唯一的 Store id,片段直接取用文件名(去掉扩展名)。例如文件命名为counter.ts,则 id 为counter。官方文档强调这个 id 用于将 Store 关联到 Devtools(见 Defining a Store 与 getting-started.md)。use${...}Store:导出的组合式函数名遵循use+ PascalCase 文件名 +Store的惯例。defineStore()返回值命名成use...是与组合式函数(composables)保持一致的惯用法。state/getters/actions三件套:分别对应组件中的data、computed与methods(可参见 core-concepts/index.md 中useCounterStore的示例)。state必须是返回对象的函数,$0是最终光标停留位置,方便你立刻开始书写 state 字段。- HMR 接线:
import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot))让 Pinia 在文件热更新时保留已有 state。
从源码看 acceptHMRUpdate 做了什么
在 packages/pinia/src/hmr.ts 中,acceptHMRUpdate 的实现揭示了模板背后完整的热更新机制:
export function acceptHMRUpdate(initialUseStore, hot) {
// strip as much as possible from iife.prod
if (!__DEV__) {
return () => {}
}
return (newModule: any) => {
const pinia: Pinia | undefined = hot.data.pinia || initialUseStore._pinia
if (!pinia) {
return
}
// preserve the pinia instance across loads
hot.data.pinia = pinia
for (const exportName in newModule) {
const useStore = newModule[exportName]
if (isUseStore(useStore) && pinia._s.has(useStore.$id)) {
const id = useStore.$id
if (id !== initialUseStore.$id) {
diagnostics.PINIA_R1005({ from: initialUseStore.$id, to: id })
return hot.invalidate()
}
const existingStore: StoreGeneric = pinia._s.get(id)!
if (!existingStore) {
console.log(`[Pinia]: skipping hmr because store doesn't exist yet`)
return
}
useStore(pinia, existingStore)
}
}
}
}
关键行为:
- 生产环境自动空转:
!__DEV__时直接返回空函数,因此模板中的 HMR 代码在打包产物中是无害的。 - 跨热更新保留 Pinia 实例:通过
hot.data.pinia在模块加载之间持久化同一个 Pinia 实例,避免热更新后丢状态。 - 只处理真实 Store:借助
isUseStore(hmr.ts)判断模块导出项是否为带$id的 StoreDefinition,再检查pinia._s中是否存在该 Store。 - id 变更检测:如果热更新后 Store id 发生变化,会触发
PINIA_R1005诊断并调用hot.invalidate()强制整页刷新——这正解释了「改 Store id 必须刷新页面」的开发经验。 - 状态合并:
useStore(pinia, existingStore)内部通过patchObject(hmr.ts)递归合并旧 state 到新 state,保留未变字段、移除新 state 中不存在的键。
你可以在 packages/pinia/tests/hmr.spec.ts 中看到针对这些行为的单元测试覆盖。
Setup Store 片段逐段解析
Setup 片段对应 Setup Stores 语法,展开后:
import { defineStore, acceptHMRUpdate } from 'pinia'
export const useCounterStore = defineStore('counter', () => {
$0
return {}
})
if (import.meta.hot) {
import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot))
}
与 Options 片段不同,defineStore 的第二个参数变成了一个函数,你可以在函数体内自由使用 ref / computed / 普通函数 / 甚至是其他组合式函数。根据官方文档(core-concepts/index.md)的约定:
ref()声明的变量成为state属性;computed()声明的变量成为getters;function()声明的函数成为actions;- 必须把要暴露的所有 state 属性放进
return {},否则 Pinia 无法识别为 state,且会影响 SSR、Devtools 与插件工作(注意不要return路由、inject得到的注入值等不属于 Store 本身的内容)。
因此模板把光标放在 $0(函数体内)并预留 return {},提醒你补全要暴露的状态与逻辑。完整可运行参考见仓库 playground 中的 counterSetup.ts,其函数体内同时使用了 reactive、toRefs、computed 与 inject,是 Setup 语法能力的直接演示。
片段变量与命名转换:TM_FILENAME_BASE 与 pascalcase
两个片段都依赖 VS Code 内置片段变量与转换:
TM_FILENAME_BASE:当前文件名去掉扩展名后的部分。文件名为user-profile.ts时值为user-profile。${TM_FILENAME_BASE/^(.*)$/${1:/pascalcase}/}:正则转换语法,把TM_FILENAME_BASE整体捕获并转换为 PascalCase。user-profile→UserProfile,counter→Counter,最终拼出useUserProfileStore/useCounterStore。
注意:
pascalcase转换要求文件名以字母开头;若文件名以数字或其他非字母字符开头,结果可能不符合预期,建议 Store 文件名始终以字母开头。
这一设计保证了「文件名 = Store id = 组合式函数名」三者一致,代码风格统一。仓库 playground 中的 counter.ts 就是这种命名惯例的直接体现:文件名为 counter.ts,Store id 为 'counter',导出函数名为 useCounter。
模板生成的 HMR 代码在实际项目中的样子
官方 HMR 指南(hot-module-replacement.md)给出了同样的接线方式,并说明:目前官方仅支持 Vite,但任何实现了 import.meta.hot 规范的打包器(如 webpack 使用 import.meta.webpackHot)理论上都可用。你需要在每个 Store 定义文件末尾都加上这段代码。
仓库中真实的 HMR 接入示例(counter.ts):
if (import.meta.hot) {
import.meta.hot.accept(acceptHMRUpdate(useCounter, import.meta.hot))
}
要点:
acceptHMRUpdate的第一个参数必须是当前文件导出的 Store 定义本身(这里是useCounter),传错会导致热更新逻辑失效;- 模板在 Options 与 Setup 两种写法下都内置了这段代码,新建 Store 文件时无需手动补写;
- 由于
acceptHMRUpdate内部有__DEV__守卫(见上文源码分析),这段代码在生产构建中会被剥离,无需担心体积与副作用。
扩展建议:把片段升级为个人模板
官方片段是极简基线,你可以基于以下方向扩展自己的版本:
- 为
state预填常用字段:如loading: false、error: null as string | null,减少重复输入; - Options 片段中为
getters预填带state参数的双倍示例,如double: (state) => state.n * 2(可参考 core-concepts/index.md 的示例); - Setup 片段中预导入
ref/computed:把import { ref, computed } from 'vue'加入 body; - 配合 TypeScript:
scope已包含typescript,在 TS 项目中可以直接获得 Store 的完整类型推断。
关于两种语法如何取舍,官方文档(core-concepts/index.md)的建议是:Options Store 上手简单、结构直观;Setup Store 更灵活强大(可写 watcher、可自由组合 composable)。两者都值得各留一个片段,按场景选用。
小结
- 复制官方片段 JSON 到 VS Code 用户代码片段,即可用
pinia-options/pinia-setup一键生成 Store 骨架; - 模板基于
TM_FILENAME_BASE+pascalcase自动推导命名,保证文件、id、函数名一致; - 模板内置的
acceptHMRUpdate接线在开发环境保留状态热更新、生产环境自动剥离,其行为可在 hmr.ts 源码与 hmr.spec.ts 测试中验证; - 在此基础上按团队规范扩展字段、导入与类型注解,即可沉淀为一套高效、统一的 Pinia 开发脚手架。