语言配置指南

The contributes.languages Contribution Point 允许你定义一个语言配置，用于控制以下声明式语言功能

• 注释切换
• 括号定义
• 自动闭合
• 自动包围
• 折叠
• 单词模式
• 缩进规则

这是一个 语言配置示例，它为 JavaScript 文件配置编辑体验。本指南解释了 language-configuration.json 的内容。

注意：如果你的语言配置文件名称为 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 和 decreaseIndentPatter 之外，还有两个其他缩进规则

• indentNextLinePattern - 如果一行匹配此模式，则仅下一行应缩进一次。
• unIndentedLinePattern - 如果一行匹配此模式，则其缩进不应该改变，也不应该针对其他规则进行评估。

如果没有为编程语言设置缩进规则，编辑器将在行以左括号结尾时缩进，并在你键入右括号时缩出。此处的括号由 brackets 定义。

请注意，editor.formatOnPaste 设置由 DocumentRangeFormattingEditProvider 控制，不受自动缩进影响。

Enter 键规则

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