Pinia 与 VS Code:用代码片段(Snippets)快速生成 Options / Setup Store 样板

原创2026-09-21 20:17:071,622 阅读
文章标签:前端状态管理

Pinia 与 VS Code:用代码片段(Snippets)快速生成 Options / Setup Store 样板

在 Pinia 项目开发中,每个 store 文件都遵循高度重复的样板结构:导入 defineStore、声明唯一的 $id、编写 state / getters / actions(或 Setup 函数)、最后再补上 acceptHMRUpdate 热更新代码。本文基于 Pinia 官方 cookbook 中的 VS Code 代码片段方案,介绍如何通过两条自定义用户片段(pinia-options 与 pinia-setup)一键生成完整、可直接运行且自带 HMR 支持的 store 模板,并结合 pinia 仓库 的 defineStore 与 hmr.ts 源码,说明片段中每个占位符与代码块背后的真实含义。读完本文,你将能够配置自己的 Pinia 片段,理解模板变量与变换语法,并掌握 Options Store 与 Setup Store 两种写法的 HMR 接入要点。

一、为什么要用代码片段生成 Pinia store

Pinia 的 store 声明通常只占几十行,但结构固定:defineStore 的导入、store id、状态/派生/行为三个部分、以及开发期的热更新接入。手动逐个输入这些内容既低效又容易遗漏,尤其容易忘记给每个 store 加上 acceptHMRUpdate,导致编辑 store 后无法在页面上实时看到效果。

VS Code 的**用户代码片段(User Snippets)**正好解决这个问题:输入一个短前缀(如 pinia-options),按回车即可展开为完整的 store 文件骨架。官方 cookbook(英文版 / 中文版)给出了两条现成的片段配置,覆盖了 Pinia 最常用的两种 store 形态:

  • Options Store:使用 state / getters / actions 对象式配置(对应 defineStore 的第一个重载,见 store.ts);
  • Setup Store:使用 Setup 函数组织响应式状态与行为(对应 defineStore 的第二个重载,见 store.ts)。

二、如何安装与管理用户代码片段

代码片段不是插件,而是纯 JSON 配置。在 VS Code 中通过以下快捷键打开命令面板:

  • macOS:⇧ ⌘ P
  • Windows / Linux:⇧ ⌃ P

输入 Snippets: Configure User Snippets 并回车,选择新建一个全局用户片段文件(如 pinia.code-snippets),把下面的 JSON 整体粘贴进去保存即可生效。片段对所有已安装工作区全局生效,之后在任何 .js / .ts(及其 Vue <script> 块)文件中输入 pinia-options 或 pinia-setup,即可看到自动补全提示。

三、片段全量配置(官方推荐版本)

以下为官方文档提供的完整片段配置,两条片段均包含:scope(适用的语言)、prefix(触发前缀)、body(展开的代码骨架)与 description(补全列表中的说明文字):

{
  "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"
  }
}

说明:body 数组中的每一项对应一行;"" 空字符串表示空行,用于在导入语句与 store 声明之间、以及 store 声明与 HMR 代码之间留出整洁的间隔。

四、逐行拆解片段中的模板变量与占位符

1. 文件名驱动的 store id 与命名

两个片段都使用了 VS Code 的模板变量与正则变换:

  • $TM_FILENAME_BASE:当前文件名去掉扩展名后的部分,例如 user.ts → user;
  • ${TM_FILENAME_BASE/^(.*)$/${1:/pascalcase}/}:对 TM_FILENAME_BASE 执行正则 ^(.*)$ 捕获整段文本,并通过 :pascalcase 变换转为帕斯卡命名(PascalCase),例如 user → User。

由此,若你新建文件 cart.ts,展开 pinia-options 后将得到 export const useCartStore = defineStore('cart', { ... })。也就是说:store 的变量名、$id 与文件名三者自动保持了一致——文件即 store id,无需手动输入,也不会因复制粘贴而出现命名错位。

从源码看,defineStore 的第一个参数 id 是 store 的唯一标识:它被保存在返回函数 useStore 的 $id 属性上(store.ts),并被写入 pinia._s 缓存中供后续取用;同时它也是 mapStores 等辅助工具与 DevTools 面板中展示的名称(类型定义见 types.ts)。因此片段把文件名作为 $id 是一种强约束下的最佳实践:每个 store 文件的 id 天然唯一。

2. $0:展开后的光标落点

$0 是 VS Code 片段中的最终光标位置(tab stop)。Options Store 片段把 $0 放在 state 的返回值对象内部,Setup Store 片段则放在 Setup 函数体内第一行。这意味着片段展开后,光标会直接停留在你添加状态属性的位置,无需手动跳过样板代码。

3. Options Store:对象式三件套

pinia-options 展开的核心骨架是:

import { defineStore, acceptHMRUpdate } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    // $0 光标落点
  }),
  getters: {},
  actions: {},
})

if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUserStore, import.meta.hot))
}

这对应 defineStore(id, options) 的 Options 写法。在 store.ts 的 createOptionsStore 中,state 函数会被调用一次以初始化 pinia.state.value[id],getters 会被逐个包装为 computed,actions 则直接合并进 store 实例。片段中预留的 getters: {} 与 actions: {} 空对象正是为这两个扩展点准备的。

4. Setup Store:函数式写法

pinia-setup 展开后的骨架为:

import { defineStore, acceptHMRUpdate } from 'pinia'

export const useUserStore = defineStore('user', () => {
  // $0 光标落点
  return {}
})

if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUserStore, import.meta.hot))
}

Setup 写法由第二个重载 defineStore(id, setup) 支持(store.ts),setup 函数中可以直接使用 ref / computed / watch 等组合式 API 组织状态与逻辑,最后通过 return {} 显式暴露给外部使用。在源码层面,defineStore 通过 typeof setup === 'function' 判断走 Setup 分支(store.ts),并最终进入 createSetupStore(store.ts)。片段用 return {} 作为占位,提醒你在函数末尾显式返回对外暴露的成员。

五、片段内置的 HMR 代码块:原理与作用

两个片段都内嵌了热更新接入代码:

if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUserStore, import.meta.hot))
}

这部分来源于 Pinia 官方的 HMR 指南(详见 hot-module-replacement.md)。理解它的关键在于 acceptHMRUpdate 的实现,见 hmr.ts:

  • 开发期守卫:在非开发构建(__DEV__ 为假)中直接返回空函数,避免生产代码携带热更新逻辑;
  • Pinia 实例的跨模块保留:通过 hot.data.pinia 缓存 Pinia 实例,使新旧模块共享同一个 store 缓存;
  • 逐导出检查:遍历新模块的每个导出,用 isUseStore(判断函数是否带有字符串类型的 $id,见 hmr.ts)识别出 store 定义;
  • id 一致性校验:如果新模块导出的 store $id 与最初注册的 $id 不一致(例如片段生成后又手动改了 store id),会触发 hot.invalidate() 做整页刷新兜底;
  • 复用旧 store 实例:最终以 useStore(pinia, existingStore) 的方式,把新模块的 store 定义应用到旧实例上——useStore 的第二个参数 hot 会触发 hot._hotUpdate(newStore) 完成 state 合并、getter/action 替换(store.ts)。

因此片段中这段 if (import.meta.hot) 代码让 store 支持热替换:修改 store 内容后浏览器不刷新,已持有的 state 会被 patchObject 递归保留(hmr.ts),而 getter 与 action 直接更新。

需要注意两点前提:

  1. 该写法依赖 Vite 及任何实现 import.meta.hot 规范的构建工具(如 Nuxt 3+、Vitest 生态);webpack 使用 import.meta.webpackHot,官方文档明确其不在支持范围内;
  2. 每个 store 声明后都必须单独添加这段代码,且必须传入对应的 store 定义函数(片段中已通过模板变量自动关联到 useXxxStore),多个 store 时不能共用一个 accept 回调。

六、从官方 cookbook 到自己的片段库

官方文档给出的两条片段是最小可用的起点,理解模板语法后,你可以基于同一套机制扩展自己的片段:

  • 增加文件头注释:在 body 首行加入 "// auto-generated by pinia snippet" 之类的说明,方便团队识别生成来源;
  • 预置常用导入:在 pinia-setup 的 body 中提前写入 import { ref, computed } from 'vue';
  • 调整 scope:如果项目使用 .vue 单文件组件且 <script setup lang="ts"> 需要补全,可把 scope 扩展为 "javascript,typescript,vue"(需配合 Volar/Vue 扩展支持);
  • 合并多条片段:同一个 .code-snippets 文件里可以同时存在多个前缀互不冲突的片段,团队可以把整套 Pinia 片段提交到仓库,实现全员统一。

七、小结

本文给出的两条 VS Code 用户片段(pinia-options 与 pinia-setup)覆盖了 Pinia 两类 store 的完整声明、命名规范与 HMR 接入,是 vscode-snippets.md 所述方案的完整落地。借助 TM_FILENAME_BASE 模板变量与 pascalcase 变换,文件名、store id 与导出命名三者自动对齐;借助 $0 光标定位,展开后即可直接开始编写业务状态。同时,acceptHMRUpdate 的接入与 Pinia 仓库中 hmr.ts 和 store.ts 的实现一一对应,保证你在开发期编辑 store 时无需刷新页面即可看到最新效果。若需要更深入的热更新细节,可继续阅读 hot-module-replacement.md 与仓库内 hmr.spec.ts 测试用例。

登录后查看全文
pinia