缘缘堂

Appearance

代码片段配置 ​

前言 ​

写代码的时候，总有一些代码是重复写的，比如每次写 Vue 组件都要写一堆 <template> <script> <style>，每次写函数都要打完整的 function。这时候代码片段（Code Snippet）就派上用场了！

代码片段就像是你预设好的"代码模板"，敲几个字母按下 Tab 键，整段代码就自动出来了，光标还会智能地跳到你需要填写的地方。

一、如何进入代码片段配置 ​

VSCode 提供了几种方式来配置代码片段：

方法一：通过命令面板 ​

  1. 按下 Cmd + Shift + P（Mac）或 Ctrl + Shift + P（Windows/Linux）打开命令面板
  2. 输入 "snippet"，选择 "配置用户代码片段"（Configure User Snippets）
  3. 这时会弹出选项让你选择：
    • 新建全局代码片段文件：所有项目通用
    • 新建当前项目代码片段文件：只在当前项目生效
    • 选择已有语言：比如 JavaScript、Vue、Markdown 等，为特定语言配置

方法二：通过菜单 ​

  • Mac：Code > 首选项 > 配置用户代码片段
  • Windows/Linux：文件 > 首选项 > 配置用户代码片段

方法三：直接创建文件 ​

代码片段文件保存在：

  • 全局：~/.config/Code/User/snippets/（Mac/Linux）或 %APPDATA%\Code\User\snippets\（Windows）
  • 项目级：项目根目录的 .vscode/ 文件夹下

二、代码片段的基本结构 ​

打开代码片段文件后，你会看到 JSON 格式的配置。每个代码片段的基本结构是这样的：

json
{
  "代码片段名称": {
    "prefix": "触发词",
    "body": [
      "代码内容第一行",
      "代码内容第二行"
    ],
    "description": "描述信息"
  }
}

举个实际例子，Vue 组件的代码片段：

json
{
  "Vue Component": {
    "prefix": "vbase",
    "body": [
      "<template>",
      "  <div>",
      "    $1",
      "  </div>",
      "</template>",
      "",
      "<script>",
      "export default {",
      "  name: '$2',",
      "  data() {",
      "    return {",
      "      $0",
      "    }",
      "  }",
      "}",
      "</script>",
      "",
      "<style scoped>",
      "</style>"
    ],
    "description": "创建基础 Vue 组件"
  }
}

三、配置属性详解 ​

1. prefix（触发词） ​

作用：这是触发代码片段的关键词，就像"咒语"一样。

用法：

  • 可以是字符串："prefix": "log"
  • 可以是数组（多个触发词）："prefix": ["log", "console"]

示例：

json
"prefix": "log"

在代码中输入 log，提示列表中就会出现这个代码片段，按 Tab 或 Enter 就能使用。

2. body（代码主体） ​

作用：这是代码片段的核心内容，也就是最终会插入到编辑器中的代码。

用法：

  • 可以是字符串："body": "console.log($1)"
  • 可以是数组（推荐）：每个元素代表一行代码

示例：

json
"body": [
  "function ${1:functionName}(${2:params}) {",
  "  ${0:// TODO}",
  "}"
]

注意：数组的好处是可读性强，每一行一目了然。

3. description（描述） ​

作用：在代码提示列表中显示的说明文字，帮助你记住这个片段是干什么的。

用法：

json
"description": "快速输出 console.log"

当你输入触发词时，VSCode 的提示框中会显示这段描述。

4. scope（作用域） ​

作用：限制代码片段在哪些语言中生效。

用法：

json
"scope": "javascript,typescript,vue"

如果不设置，代码片段在所有文件中都会生效。设置后只在指定语言中生效。

四、重点：占位符与光标控制 ​

这是代码片段最强大的功能！通过特殊的占位符，你可以控制光标的跳转顺序和默认值。

基础占位符：$1、$2、$3... ​

作用：定义光标的跳转顺序。

使用规则：

  • $1：代码片段插入后，光标会首先停在这里
  • $2：按下 Tab 键，光标跳到第二个位置
  • $3、$4...：依此类推，按 Tab 依次跳转

示例 1：简单的 console.log

json
{
  "Console Log": {
    "prefix": "log",
    "body": "console.log($1)",
    "description": "输出日志"
  }
}

效果：

  1. 输入 log 按 Tab
  2. 代码变成 console.log(█)（█ 表示光标位置）
  3. 直接输入内容即可

示例 2：多个占位符的函数

json
{
  "Function": {
    "prefix": "fn",
    "body": [
      "function $1($2) {",
      "  $3",
      "}"
    ],
    "description": "创建函数"
  }
}

效果：

  1. 输入 fn 按 Tab
  2. 光标停在函数名位置（$1），输入函数名，比如 getName
  3. 按 Tab，光标跳到参数位置（$2），输入参数，比如 user
  4. 再按 Tab，光标跳到函数体（$3），写逻辑

带默认值的占位符：$ ​

作用：不仅定义光标位置，还提供默认值。默认值会被选中，你可以直接覆盖，也可以按 Tab 跳过使用默认值。

语法：${序号:默认值}

示例 1：带默认函数名

json
{
  "Function with Default": {
    "prefix": "func",
    "body": [
      "function ${1:myFunction}(${2:params}) {",
      "  ${3:// TODO: 实现功能}",
      "}"
    ],
    "description": "创建带默认值的函数"
  }
}

效果：

  1. 输入 func 按 Tab
  2. myFunction 被选中（高亮状态）
    • 如果你想改名字，直接输入会覆盖
    • 如果你觉得这个名字就挺好，按 Tab 跳到下一个位置
  3. 光标跳到参数处，params 被选中
  4. 再按 Tab，光标跳到函数体，// TODO: 实现功能 被选中

示例 2：Vue Prop 定义

json
{
  "Vue Prop": {
    "prefix": "vprop",
    "body": [
      "${1:propName}: {",
      "  type: ${2:String},",
      "  default: ${3:''}",
      "}"
    ],
    "description": "Vue prop 定义"
  }
}

特殊占位符：$0 ​

作用：$0 是最终光标停留的位置，不管前面有多少个占位符。

规则：

  • $0 是最后一个跳转点
  • 如果不写 $0，光标会默认停在代码片段的末尾
  • 一个代码片段中只能有一个 $0

示例：完整的 Vue 组件

json
{
  "Vue Component Full": {
    "prefix": "vcomp",
    "body": [
      "<template>",
      "  <div class=\"${1:container}\">",
      "    ${2:内容}",
      "  </div>",
      "</template>",
      "",
      "<script>",
      "export default {",
      "  name: '${3:ComponentName}',",
      "  data() {",
      "    return {",
      "      $0",
      "    }",
      "  }",
      "}",
      "</script>"
    ],
    "description": "完整 Vue 组件"
  }
}

使用流程：

  1. 输入 vcomp 按 Tab
  2. container 被选中（$1），输入类名或按 Tab 跳过
  3. 光标跳到 内容（$2），输入模板内容或按 Tab
  4. 光标跳到 ComponentName（$3），输入组件名
  5. 按 Tab，光标直接跳到 data 的 return 对象中（$0）
  6. 现在你可以定义数据了，不需要再手动移动光标

相同序号的占位符：同步编辑 ​

作用：多个地方使用相同的序号，可以实现同步编辑。

示例：React 组件

json
{
  "React Component": {
    "prefix": "rfc",
    "body": [
      "function ${1:ComponentName}() {",
      "  return (",
      "    <div className=\"${1:ComponentName}\">",
      "      $0",
      "    </div>",
      "  );",
      "}",
      "",
      "export default ${1:ComponentName};"
    ],
    "description": "React 函数组件"
  }
}

效果：

  • 当你在第一个 $1 位置输入组件名，比如 UserCard
  • 所有标记为 $1 的地方会同步更新
  • 函数名、className、export 的名称都变成 UserCard
  • 按 Tab，光标跳到 $0，也就是 div 内部

实用技巧总结 ​

语法说明示例
$1, $2, $3光标跳转顺序console.log($1)
${1:default}带默认值的占位符function ${1:myFunc}() {}
$0最终光标位置if ($1) { $0 }
相同序号同步编辑const $1 = $1

按 Tab 键的作用：

  • 在占位符之间跳转
  • 如果占位符有默认值，可以选择接受默认值并跳到下一个

按 Esc 键的作用：

  • 退出代码片段模式，光标停在当前位置

五、更多高级特性 ​

1. 变量（Variables） ​

VSCode 提供了很多内置变量，可以动态插入信息：

json
{
  "File Header": {
    "prefix": "header",
    "body": [
      "/**",
      " * @file ${TM_FILENAME}",
      " * @author ${1:YourName}",
      " * @date ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
      " * @description ${2:文件描述}",
      " */",
      "$0"
    ],
    "description": "文件头注释"
  }
}

常用变量：

  • $TM_FILENAME：当前文件名
  • $TM_FILENAME_BASE：不含扩展名的文件名
  • $CURRENT_YEAR：当前年份
  • $CURRENT_MONTH：当前月份
  • $CURRENT_DATE：当前日期
  • $CLIPBOARD：剪贴板内容

2. 选择列表（Choice） ​

可以让用户从预设选项中选择：

json
{
  "Vue Lifecycle": {
    "prefix": "vlife",
    "body": [
      "${1|created,mounted,updated,destroyed|}() {",
      "  $0",
      "}"
    ],
    "description": "Vue 生命周期"
  }
}

效果：输入后会弹出选项列表，选择一个生命周期钩子。

3. 正则转换（Transform） ​

可以对输入的内容进行转换，比如转大写、转小写等。这个比较高级，日常使用较少。

六、实战案例 ​

案例 1：快速创建 console.log ​

json
{
  "Console Log Variable": {
    "prefix": "clg",
    "body": [
      "console.log('${1:变量名}:', $1);",
      "$0"
    ],
    "description": "输出变量名和值"
  }
}

使用效果：

  1. 输入 clg 按 Tab
  2. 输入变量名，比如 user
  3. 自动生成 console.log('user:', user);
  4. 因为两个 $1 同步，变量名只需要输入一次

案例 2：try-catch 块 ​

json
{
  "Try Catch": {
    "prefix": "tryc",
    "body": [
      "try {",
      "  $1",
      "} catch (${2:error}) {",
      "  console.error('${3:错误描述}:', $2);",
      "  $0",
      "}"
    ],
    "description": "try-catch 错误处理"
  }
}

案例 3：Vue 3 setup 组件 ​

json
{
  "Vue 3 Setup": {
    "prefix": "v3setup",
    "body": [
      "<template>",
      "  <div>",
      "    {{ ${1:message} }}",
      "  </div>",
      "</template>",
      "",
      "<script setup>",
      "import { ref } from 'vue';",
      "",
      "const ${1:message} = ref('${2:Hello Vue 3}');",
      "$0",
      "</script>",
      "",
      "<style scoped>",
      "</style>"
    ],
    "description": "Vue 3 Composition API 组件"
  }
}

七、代码片段生成器工具 ​

手写 JSON 格式的代码片段有时候会比较麻烦，特别是要处理缩进、引号转义等问题。推荐使用在线工具来生成：

🔧 Snippet Generator ​

网址：https://snippet-generator.app/?description=&tabtrigger=&snippet=&mode=vscode

使用方法：

  1. 打开网站
  2. Description：输入代码片段的描述
  3. Tab trigger：输入触发词（prefix）
  4. Your snippet：直接粘贴你想要的代码模板
  5. 在代码中手动添加 $1、$2、$0 等占位符
  6. 右侧会自动生成 VSCode 格式的 JSON
  7. 复制生成的 JSON，粘贴到你的代码片段文件中

优点：

  • 自动处理 JSON 格式
  • 自动转义特殊字符
  • 实时预览效果
  • 支持多种编辑器格式（VSCode、Sublime、Atom 等）

小技巧：

  • 先在编辑器中写好代码模板
  • 在需要停留光标的地方标记出来
  • 复制到 Snippet Generator
  • 把标记替换成 $1、$2 等
  • 复制生成的 JSON 即可

八、最佳实践建议 ​

  1. 命名要清晰：代码片段的名称和触发词都要一目了然
  2. 触发词要简短：常用的代码片段用 3-5 个字母就够了
  3. 合理使用占位符：不要过度使用，只在真正需要填写的地方用
  4. 善用默认值：为占位符提供有意义的默认值，提高效率
  5. $0 放在最有用的位置：通常是代码块的核心区域
  6. 项目级代码片段：团队协作时，可以把代码片段放在项目的 .vscode 目录下，统一代码风格
  7. 定期整理：删除不用的代码片段，保持列表清爽

九、常见问题 ​

Q: 为什么我的代码片段不生效？

  • 检查 JSON 格式是否正确（逗号、引号等）
  • 检查 scope 是否限制了语言
  • 重启 VSCode 试试

Q: 如何在字符串中使用 $ 符号？

  • 使用 \\$ 转义

Q: 能导入别人的代码片段吗？

  • 可以！找到代码片段文件（.code-snippets），复制到你的 snippets 目录即可

Q: 代码片段太多记不住怎么办？

  • 只保留常用的，删除不常用的
  • 给触发词起有规律的名字，比如 Vue 相关的都用 v 开头

总结 ​

代码片段是提高编码效率的利器，掌握了占位符的使用，你就能创建出非常智能的代码模板。

核心要点回顾：

  • $1, $2, $3...：定义光标跳转顺序
  • ${1:default}：带默认值，可覆盖可跳过
  • $0：最终光标位置
  • 相同序号：同步编辑
  • Tab 键：在占位符间跳转
  • Snippet Generator：方便生成配置

现在就去配置几个你常用的代码片段吧，相信我，用过之后你会爱上这种感觉的！

Released under the MIT License.

Copyright © 2019-present Evan You