Visual Studio Code 中的代码片段

代码片段是模板，可以更轻松地输入重复的代码模式，例如循环或条件语句。

在 Visual Studio Code 中，代码片段会出现在 IntelliSense 中 (⌃Space (Windows、Linux Ctrl+Space)) 与其他建议混合在一起，以及在专用的代码片段选取器中（命令面板中的“插入代码片段”）。还支持 Tab 键补全：通过 "editor.tabCompletion": "on" 启用它，键入一个代码片段前缀（触发文本），然后按 Tab 来插入代码片段。

代码片段语法遵循 TextMate 代码片段语法，但“插入的 Shell 代码”和 \u 的使用除外；这两者都不受支持。

内置代码片段

VS Code 为多种语言（例如：JavaScript、TypeScript、Markdown 和 PHP）提供了内置的代码片段。

您可以通过在命令面板中运行“插入代码片段”命令来查看某种语言的可用代码片段，以获取当前文件语言的代码片段列表。但是，请记住，此列表还包括您已定义的用户代码片段以及您已安装的扩展提供的任何代码片段。

从 Marketplace 安装代码片段

Marketplace 上的许多 扩展 VS Code Marketplace 都包含代码片段。您可以使用 @category:"snippets" 筛选器在“扩展”视图中 (⇧⌘X (Windows、Linux Ctrl+Shift+X)) 搜索包含代码片段的扩展。

如果您找到想要使用的扩展，请安装它，然后重新启动 VS Code，新的代码片段将可用。

创建您自己的代码片段

您可以轻松地定义自己的代码片段，而无需任何扩展。要创建或编辑您自己的代码片段，请在 文件 > 首选项 下选择“配置用户代码片段”，然后选择代码片段应显示的语言（通过语言标识符），或者如果它们应显示在所有语言中，则选择“新建全局代码片段文件”选项。VS Code 会为您管理基础代码片段文件的创建和刷新。

代码片段文件以 JSON 编写，支持 C 样式的注释，并且可以定义无限数量的代码片段。代码片段支持大多数用于动态行为的 TextMate 语法，可以根据插入上下文智能地格式化空格，并允许轻松进行多行编辑。

下面是一个 JavaScript 的 for 循环代码片段的示例

// in file 'Code/User/snippets/javascript.json'
{
  "For Loop": {
    "prefix": ["for", "for-const"],
    "body": ["for (const ${2:element} of ${1:array}) {", "\t$0", "}"],
    "description": "A for loop."
  }
}

在上面的示例中

• “For Loop”是代码片段的名称。如果没有提供 description，则通过 IntelliSense 显示。
• prefix 定义一个或多个触发词，用于在 IntelliSense 中显示代码片段。前缀会执行子字符串匹配，因此在这种情况下，“fc”可能与“for-const”匹配。
• body 是一行或多行内容，这些内容将在插入时连接为多行。换行符和嵌入的制表符将根据插入代码片段的上下文进行格式化。
• description 是 IntelliSense 显示的（可选）代码片段说明。

此外，上面示例的 body 具有三个占位符（按遍历顺序列出）：${1:array}、${2:element} 和 $0。您可以使用 Tab 快速跳转到下一个占位符，此时您可以编辑占位符或跳转到下一个占位符。冒号 : 之后的字符串（如果有）是默认文本，例如 ${2:element} 中的 element。占位符遍历顺序按数字升序，从一开始；零是一个可选的特殊情况，它始终排在最后，并在光标位于指定位置时退出代码片段模式。

文件模板代码片段

如果代码片段旨在填充或替换文件内容，则可以将 isFileTemplate 属性添加到代码片段的定义。当您在新文件或现有文件中运行“代码片段：从代码片段填充文件”命令时，文件模板代码片段会显示在下拉列表中。

代码片段范围

代码片段的作用域已限定，因此只会建议相关的代码片段。代码片段可以按以下方式限定作用域

1. 代码片段的作用域所限定的语言（可能全部）
2. 代码片段的作用域所限定的项目（可能全部）

语言代码片段作用域

每个代码片段都根据它定义在以下位置而被限定到一个、多个或全部（“全局”）语言

1. 语言代码片段文件
2. 全局代码片段文件

单语言用户定义的代码片段在特定语言的代码片段文件（例如 javascript.json）中定义，您可以通过“代码片段：配置用户代码片段”通过语言标识符访问该文件。只有在编辑定义该代码片段的语言时，才能访问该代码片段。

多语言和全局用户自定义代码片段都定义在“全局”代码片段文件（带有 .code-snippets 文件后缀的 JSON 文件）中，也可以通过 代码片段：配置用户代码片段 访问。在全局代码片段文件中，一个代码片段定义可能有一个额外的 scope 属性，该属性接受一个或多个语言标识符，这使得该代码片段仅对那些指定的语言可用。如果没有给出 scope 属性，则全局代码片段在所有语言中都可用。

大多数用户自定义代码片段的作用域限定为单一语言，因此定义在特定于语言的代码片段文件中。

项目代码片段作用域

您还可以拥有一个作用域限定为您的项目的全局代码片段文件（带有 .code-snippets 文件后缀的 JSON 文件）。项目文件夹代码片段是通过 代码片段：配置用户代码片段 下拉菜单中的 为“<文件夹名称>”新建代码片段文件... 选项创建的，并位于项目根目录的 .vscode 文件夹中。项目代码片段文件对于与在该项目中工作的所有用户共享代码片段很有用。项目文件夹代码片段类似于全局代码片段，可以通过 scope 属性将其作用域限定为特定的语言。

代码片段语法

代码片段的 body 可以使用特殊的构造来控制光标和插入的文本。以下是支持的功能及其语法

制表位

使用制表位，您可以使编辑器光标在代码片段内移动。使用 $1、$2 来指定光标位置。数字是制表位被访问的顺序，而 $0 表示最终的光标位置。同一个制表位的多次出现是链接的并同步更新的。

占位符

占位符是带有值的制表位，例如 ${1:foo}。占位符文本将被插入并选中，以便可以轻松更改它。占位符可以嵌套，例如 ${1:另一个 ${2:占位符}}。

选择

占位符可以具有作为值的选择。语法是用竖线字符括起来的逗号分隔的值枚举，例如 ${1|one,two,three|}。当插入代码片段并选择占位符时，选择将提示用户选择其中一个值。

变量

使用 $name 或 ${name:default}，您可以插入变量的值。当变量未设置时，将插入其默认值或空字符串。当变量未知（即，其名称未定义）时，将插入变量的名称，并将其转换为占位符。

可以使用以下变量

• TM_SELECTED_TEXT 当前选定的文本或空字符串
• TM_CURRENT_LINE 当前行的内容
• TM_CURRENT_WORD 光标下的单词的内容或空字符串
• TM_LINE_INDEX 基于零索引的行号
• TM_LINE_NUMBER 基于一索引的行号
• TM_FILENAME 当前文档的文件名
• TM_FILENAME_BASE 当前文档的文件名，不带其扩展名
• TM_DIRECTORY 当前文档的目录
• TM_FILEPATH 当前文档的完整文件路径
• RELATIVE_FILEPATH 当前文档的相对（相对于打开的工作区或文件夹）文件路径
• CLIPBOARD 剪贴板的内容
• WORKSPACE_NAME 打开的工作区或文件夹的名称
• WORKSPACE_FOLDER 打开的工作区或文件夹的路径
• CURSOR_INDEX 基于零索引的光标编号
• CURSOR_NUMBER 基于一索引的光标编号

对于插入当前日期和时间

• CURRENT_YEAR 当前年份
• CURRENT_YEAR_SHORT 当前年份的最后两位数字
• CURRENT_MONTH 月份，两位数字（例如 '02'）
• CURRENT_MONTH_NAME 月份的完整名称（例如 'July'）
• CURRENT_MONTH_NAME_SHORT 月份的短名称（例如 'Jul'）
• CURRENT_DATE 月份的日期，两位数字（例如 '08'）
• CURRENT_DAY_NAME 日期的名称（例如 'Monday'）
• CURRENT_DAY_NAME_SHORT 日期的短名称（例如 'Mon'）
• CURRENT_HOUR 当前小时，24 小时制格式
• CURRENT_MINUTE 当前分钟，两位数字
• CURRENT_SECOND 当前秒，两位数字
• CURRENT_SECONDS_UNIX 自 Unix 纪元以来的秒数
• CURRENT_TIMEZONE_OFFSET 当前 UTC 时区偏移量，格式为 +HH:MM 或 -HH:MM （例如 -07:00）。

对于插入随机值

• RANDOM 6 位随机十进制数字
• RANDOM_HEX 6 位随机十六进制数字
• UUID 版本 4 UUID

对于插入行或块注释，遵守当前语言

• BLOCK_COMMENT_START 示例输出：在 PHP 中为 /*，在 HTML 中为 <!--
• BLOCK_COMMENT_END 示例输出：在 PHP 中为 */，在 HTML 中为 -->
• LINE_COMMENT 示例输出：在 PHP 中为 //

下面的代码片段在 JavaScript 文件中插入 /* Hello World */，在 HTML 文件中插入 <!-- Hello World -->

{
  "hello": {
    "scope": "javascript,html",
    "prefix": "hello",
    "body": "$BLOCK_COMMENT_START Hello World $BLOCK_COMMENT_END"
  }
}

变量转换

转换允许您在插入变量的值之前修改它。转换的定义由三个部分组成

1. 一个正则表达式，它与变量的值进行匹配，或者当无法解析变量时，与空字符串匹配。
2. 一个“格式字符串”，允许引用正则表达式中的匹配组。格式字符串允许有条件地插入和进行简单的修改。
3. 传递给正则表达式的选项。

以下示例插入当前文件的名称，不带其结尾，因此从 foo.txt 变为 foo。

${TM_FILENAME/(.*)\\..+$/$1/}
  |           |         |  |
  |           |         |  |-> no options
  |           |         |
  |           |         |-> references the contents of the first
  |           |             capture group
  |           |
  |           |-> regex to capture everything before
  |               the final `.suffix`
  |
  |-> resolves to the filename

占位符转换

与变量转换类似，占位符的转换允许在移动到下一个制表位时更改占位符的插入文本。插入的文本与正则表达式匹配，并且匹配项或多个匹配项（取决于选项）将替换为指定的替换格式文本。占位符的每次出现都可以使用第一个占位符的值独立定义其自己的转换。占位符转换的格式与变量转换的格式相同。

转换示例

这些示例显示在双引号内，因为它们会出现在代码片段主体中，以说明需要对某些字符进行双重转义。文件名为 example-123.456-TEST.js 的示例转换和结果输出。

语法

以下是代码片段的 EBNF（扩展巴科斯-瑙尔范式）。使用 \（反斜杠），您可以转义 $、} 和 \。在选择元素中，反斜杠还会转义逗号和竖线字符。只能转义需要转义的字符，因此不应在这些结构中转义 $，并且不应在选择结构中转义 $ 或 }。

any         ::= tabstop | placeholder | choice | variable | text
tabstop     ::= '$' int
                | '${' int '}'
                | '${' int  transform '}'
placeholder ::= '${' int ':' any '}'
choice      ::= '${' int '|' text (',' text)* '|}'
variable    ::= '$' var | '${' var '}'
                | '${' var ':' any '}'
                | '${' var transform '}'
transform   ::= '/' regex '/' (format | text)+ '/' options
format      ::= '$' int | '${' int '}'
                | '${' int ':' '/upcase' | '/downcase' | '/capitalize' | '/camelcase' | '/pascalcase' '}'
                | '${' int ':+' if '}'
                | '${' int ':?' if ':' else '}'
                | '${' int ':-' else '}' | '${' int ':' else '}'
regex       ::= JavaScript Regular Expression value (ctor-string)
options     ::= JavaScript Regular Expression option (ctor-options)
var         ::= [_a-zA-Z] [_a-zA-Z0-9]*
int         ::= [0-9]+
text        ::= .*
if          ::= text
else        ::= text

使用 TextMate 代码片段

您还可以将现有的 TextMate 代码片段 (.tmSnippets) 与 VS Code 一起使用。请参阅我们的扩展 API 部分中的使用 TextMate 代码片段主题以了解更多信息。

将快捷键绑定到代码片段

您可以创建自定义的键绑定以插入特定的代码片段。打开 keybindings.json (首选项：打开键盘快捷方式文件)，其中定义了您的所有键绑定，并添加一个将 "snippet" 作为额外参数传递的键绑定

{
  "key": "cmd+k 1",
  "command": "editor.action.insertSnippet",
  "when": "editorTextFocus",
  "args": {
    "snippet": "console.log($1)$0"
  }
}

该键绑定将调用 插入代码片段 命令，但它不会提示您选择代码片段，而是会插入提供的代码片段。您可以像往常一样定义自定义的键绑定，包括键盘快捷方式、命令 ID 和可选的 when 子句上下文，用于启用键盘快捷方式。

此外，您可以使用 langId 和 name 参数引用现有的代码片段，而不是使用 snippet 参数值来内联定义代码片段。langId 参数选择要插入由 name 表示的代码片段的语言，例如，下面的示例选择可用于 csharp 文件的 myFavSnippet。

{
  "key": "cmd+k 1",
  "command": "editor.action.insertSnippet",
  "when": "editorTextFocus",
  "args": {
    "langId": "csharp",
    "name": "myFavSnippet"
  }
}

后续步骤

• 命令行 - VS Code 具有丰富的命令行界面，可以打开或比较文件并安装扩展。
• 扩展 API - 了解扩展 VS Code 的其他方法。
• 代码片段指南 - 您可以打包代码片段以在 VS Code 中使用。

常见问题

如果我想使用 .tmSnippet 文件中的现有 TextMate 代码片段怎么办？

您可以轻松打包 TextMate 代码片段文件以在 VS Code 中使用。请参阅我们的扩展 API 文档中的使用 TextMate 代码片段。

如何让代码片段在粘贴的脚本中放置一个变量？

要使粘贴的脚本中包含变量，您需要转义 $variable 名称的 '$'，以使其不被代码片段扩展阶段解析。

"VariableSnippet":{
    "prefix": "_Var",
    "body": "\\$MyVar = 2",
    "description": "A basic snippet that places a variable into script with the $ prefix"
  }

这导致粘贴的代码片段如下

$MyVar = 2

我可以从 IntelliSense 中删除代码片段吗？

是的，您可以通过在 插入代码片段 命令下拉菜单中选择代码片段项目右侧的 从 IntelliSense 中隐藏 按钮，来隐藏 IntelliSense（完成列表）中显示的特定代码片段。

您仍然可以使用 插入代码片段 命令选择代码片段，但隐藏的代码片段不会显示在 IntelliSense 中。