语言配置指南
contributes.languages
贡献点允许你定义一个语言配置,用于控制以下声明式语言特性
- 注释切换
- 括号定义
- 自动闭合
- 自动包围
- 折叠
- 单词模式
- 缩进规则
这里有一个配置 JavaScript 文件编辑体验的语言配置示例。本指南解释了 language-configuration.json
的内容。
注意:如果你的语言配置文件名是或以 language-configuration.json
结尾,你将在 VS Code 中获得自动补全和验证。
{
"comments": {
"lineComment": "//",
"blockComment": ["/*", "*/"]
},
"brackets": [
["{", "}"],
["[", "]"],
["(", ")"]
],
"autoClosingPairs": [
{ "open": "{", "close": "}" },
{ "open": "[", "close": "]" },
{ "open": "(", "close": ")" },
{ "open": "'", "close": "'", "notIn": ["string", "comment"] },
{ "open": "\"", "close": "\"", "notIn": ["string"] },
{ "open": "`", "close": "`", "notIn": ["string", "comment"] },
{ "open": "/**", "close": " */", "notIn": ["string"] }
],
"autoCloseBefore": ";:.,=}])>` \n\t",
"surroundingPairs": [
["{", "}"],
["[", "]"],
["(", ")"],
["'", "'"],
["\"", "\""],
["`", "`"]
],
"folding": {
"markers": {
"start": "^\\s*//\\s*#?region\\b",
"end": "^\\s*//\\s*#?endregion\\b"
}
},
"wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)",
"indentationRules": {
"increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
"decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
}
}
注释切换
VS Code 提供了两个用于注释切换的命令:切换行注释和切换块注释。你可以指定 comments.blockComment
和 comments.lineComment
来控制 VS Code 如何注释行/块。
{
"comments": {
"lineComment": "//",
"blockComment": ["/*", "*/"]
}
}
括号定义
当你将光标移动到此处定义的括号时,VS Code 将突出显示该括号及其匹配的配对。
{
"brackets": [
["{", "}"],
["[", "]"],
["(", ")"]
]
}
此外,当你运行转到括号或选择到括号时,VS Code 将使用上述定义来查找最近的括号及其匹配的配对。
自动闭合
当你键入 '
时,VS Code 会创建一对单引号并将光标放在中间:'|'
。本节定义了此类配对。
{
"autoClosingPairs": [
{ "open": "{", "close": "}" },
{ "open": "[", "close": "]" },
{ "open": "(", "close": ")" },
{ "open": "'", "close": "'", "notIn": ["string", "comment"] },
{ "open": "\"", "close": "\"", "notIn": ["string"] },
{ "open": "`", "close": "`", "notIn": ["string", "comment"] },
{ "open": "/**", "close": " */", "notIn": ["string"] }
]
}
notIn
键在某些代码范围内禁用此功能。例如,当你编写以下代码时
// ES6's Template String
`ES6's Template String`;
单引号将不会自动闭合。
不需要 notIn
属性的配对也可以使用更简单的语法
{
"autoClosingPairs": [
["{", "}"],
["[", "]"]
]
}
用户可以通过 editor.autoClosingQuotes
和 editor.autoClosingBrackets
设置调整自动闭合行为。
前置自动闭合
默认情况下,如果光标后面有空白符,VS Code 才会自动闭合配对。因此,当你在以下 JSX 代码中键入 {
时,不会自动闭合。
const Component = () =>
<div className={>
^ Does not get autoclosed by default
</div>
但是,此定义会覆盖该行为
{
"autoCloseBefore": ";:.,=}])>` \n\t"
}
现在,当你键入 {
并在 >
之前,VS Code 会用 }
自动闭合它。
自动包围
当你在 VS Code 中选择一个范围并输入一个开括号时,VS Code 会用一对括号包围选定的内容。此功能称为自动包围,你可以在此处定义特定语言的自动包围配对。
{
"surroundingPairs": [
["{", "}"],
["[", "]"],
["(", ")"],
["'", "'"],
["\"", "\""],
["`", "`"]
]
}
用户可以通过 editor.autoSurround
设置调整自动包围行为。
折叠
在 VS Code 中,折叠是基于缩进定义,或由贡献的折叠范围提供程序定义。
- 基于标记的缩进折叠:如果给定语言没有可用的折叠范围提供程序,或者用户已将
editor.foldingStrategy
设置为indentation
,则使用基于缩进的折叠。当一行的缩进小于一行或多行后续行时,折叠区域开始;当有一行具有相同或更小的缩进时,折叠区域结束。空行将被忽略。此外,语言配置可以定义开始和结束标记。这些在folding.markers
中定义为start
和end
正则表达式。当找到匹配行时,会在配对内部创建一个折叠范围。折叠标记必须非空,通常看起来像//#region
和//#endregion
。
以下 JSON 为 //#region
和 //#endregion
创建折叠标记。
{
"folding": {
"markers": {
"start": "^\\s*//\\s*#?region\\b",
"end": "^\\s*//\\s*#?endregion\\b"
}
}
}
- 语言服务器折叠:语言服务器响应
textDocument/foldingRange
请求并提供一个折叠范围列表,VS Code 会将这些范围渲染为折叠标记。在编程语言特性主题中了解更多关于语言服务器协议中的折叠支持。
单词模式
wordPattern
定义了在编程语言中什么是单词。如果设置了 wordPattern
,代码建议功能将使用此设置来确定单词边界。请注意,此设置不会影响与单词相关的编辑器命令,这些命令由编辑器设置 editor.wordSeparators
控制。
{
"wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)"
}
缩进规则
indentationRules
定义了在你键入、粘贴和移动行时,编辑器应如何调整当前行或下一行的缩进。
{
"indentationRules": {
"increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
"decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
}
}
例如,if (true) {
匹配 increaseIndentPattern
,那么如果你在开括号 {
之后按下 Enter,编辑器将自动缩进一次,你的代码将变成
if (true) {
console.log();
除了 increaseIndentPattern
和 decreaseIndentPattern
之外,还有另外两个缩进规则
indentNextLinePattern
- 如果一行匹配此模式,则只有其后下一行应缩进一次。unIndentedLinePattern
- 如果一行匹配此模式,则其缩进不应更改,并且不应根据其他规则进行评估。
如果没有为编程语言设置缩进规则,则当行以开括号结尾时,编辑器将缩进;当你键入闭括号时,编辑器将取消缩进。此处的括号由 brackets
定义。
请注意,editor.formatOnPaste
设置由 DocumentRangeFormattingEditProvider
控制,不受自动缩进影响。
回车规则
onEnterRules
定义了当在编辑器中按下 Enter 键时将评估的规则列表。
{
"onEnterRules": [
{
"beforeText": "^\\s*(?:def|class|for|if|elif|else|while|try|with|finally|except|async).*?:\\s*$",
"action": { "indent": "indent" }
}
]
}
按下 Enter 键时,将根据以下属性检查光标之前、之后或上方一行的文本:
beforeText
(必需)。匹配光标前文本(限于当前行)的正则表达式。afterText
。匹配光标后文本(限于当前行)的正则表达式。previousLineText
。匹配光标上方一行文本的正则表达式。
如果所有指定属性都匹配,则认为规则匹配,并且不会再评估其他 onEnterRules
。一个 onEnterRule
可以指定以下操作:
indent
(必需)。none、indent、outdent、indentOutdent
之一。none
意味着新行将继承当前行的缩进。indent
意味着新行将相对于当前行缩进。outdent
意味着新行将相对于当前行取消缩进。indentOutdent
意味着将插入两个新行,一个缩进,第二个取消缩进。
appendText
。一个将在新行和缩进之后追加的字符串。removeText
。从新行缩进中移除的字符数。