语言配置指南

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。要从新行缩进中移除的字符数。