用 VS Code 代码片段快速生成 Pinia Store:Options 与 Setup 双语法脚手架指南

原创2026-09-21 17:51:221,983 阅读
文章标签:前端状态管理

用 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 开发脚手架。
登录后查看全文
pinia