Visual Studio Code

语言配置指南

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": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"]
  ]
}

此外，当您运行Go to Bracket或Select to Bracket时，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 控制，不受自动缩进的影响。

进入规则

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