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 安装代码片段
许多 扩展在 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
属性添加到代码片段的定义中。当您在新文件或现有文件中运行 代码片段:从代码片段填充文件 命令时,文件模板代码片段将显示在下拉列表中。
代码片段作用域
代码片段具有作用域,以便仅建议相关的代码片段。代码片段可以按以下方式划分作用域
- 代码片段作用域所针对的语言(可能是全部)
- 代码片段作用域所针对的项目(可能全部)
语言代码片段作用域
每个代码片段都根据其定义位置,作用域限定为一种、几种或所有(“全局”)语言
- 语言代码片段文件
- 全局代码片段文件
单语言用户定义的代码片段在特定语言的代码片段文件(例如 javascript.json
)中定义,您可以通过代码片段:配置代码片段按语言标识符访问该文件。代码片段仅在编辑为其定义的语言时才可访问。
多语言和全局用户定义的代码片段都在“全局”代码片段文件(JSON,文件后缀为 .code-snippets
)中定义,也可以通过 代码片段:配置代码片段 访问。在全局代码片段文件中,代码片段定义可能具有额外的 scope
属性,该属性接受一个或多个 语言标识符,这使得代码片段仅对那些指定的语言可用。如果未给出 scope
属性,则全局代码片段在所有语言中都可用。
大多数用户定义的代码片段的作用域都限定为单一语言,因此在特定于语言的代码片段文件中定义。
项目代码片段作用域
您还可以拥有作用域限定为您的项目的全局代码片段文件(JSON,文件后缀为 .code-snippets
)。项目文件夹代码片段是使用 代码片段:配置代码片段 下拉菜单中的 新建“.vscode
文件夹中。项目代码片段文件对于与在该项目中工作的所有用户共享代码片段很有用。项目文件夹代码片段类似于全局代码片段,并且可以通过 scope
属性将其作用域限定为特定语言。
代码片段语法
代码片段的 body
可以使用特殊构造来控制光标和插入的文本。以下是受支持的功能及其语法
制表位
使用制表位,您可以使编辑器光标在代码片段内移动。使用 $1
、$2
指定光标位置。数字是制表位将被访问的顺序,而 $0
表示最终光标位置。同一制表位的多次出现会链接在一起并同步更新。
占位符
占位符是带有值的制表位,例如 ${1:foo}
。占位符文本将被插入和选中,以便可以轻松更改。占位符可以嵌套,例如 ${1:another ${2:placeholder}}
。
选择
占位符可以具有作为值的选择。语法是以逗号分隔的值枚举,用管道字符括起来,例如 ${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"
}
}
变量转换
转换允许您在插入变量之前修改变量的值。转换的定义包含三个部分
- 与变量值匹配的正则表达式,或者当无法解析变量时为空字符串。
- 允许引用正则表达式中匹配组的“格式字符串”。格式字符串允许条件插入和简单修改。
- 传递给正则表达式的选项。
以下示例插入当前文件名,但不带结尾,因此从 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
的结果输出。
示例 | 输出 | 说明 |
---|---|---|
“${TM_FILENAME/[\\.]/_/}” |
example-123_456-TEST.js |
将第一个 . 替换为 _ |
“${TM_FILENAME/[\\.-]/_/g}” |
example_123_456_TEST_js |
将每个 . 或 - 替换为 _ |
“${TM_FILENAME/(.*)/${1:/upcase}/}” |
EXAMPLE-123.456-TEST.JS |
更改为全部大写 |
“${TM_FILENAME/[^0-9a-z]//gi}” |
example123456TESTjs |
删除非字母数字字符 |
语法
以下是代码片段的 EBNF (扩展巴科斯-诺尔范式)。使用 \
(反斜杠),您可以转义 $
、}
和 \
。在 choice 元素中,反斜杠还会转义逗号和管道字符。只有需要转义的字符才能被转义,因此不应在这些构造中转义 $
,也不应在 choice 构造中转义 $
或 }
。
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 子句上下文,用于指定何时启用键盘快捷方式。
此外,除了使用 snippet
参数值内联定义代码片段之外,您还可以通过使用 langId
和 name
参数来引用现有代码片段。langId
参数选择插入 name
表示的代码片段的语言,例如,下面的示例选择 myFavSnippet
,该代码片段可用于 csharp
文件。
{
"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 中。