🚀 在 VS 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.blockCommentcomments.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.autoClosingQuoteseditor.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 中定义为 startend 正则表达式。当找到匹配行时,将在该对内部创建折叠范围。折叠标记必须为非空,通常看起来像 //#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();

除了 increaseIndentPatterndecreaseIndentPatter 之外,还有两个其他缩进规则

  • indentNextLinePattern - 如果一行匹配此模式,则仅应将紧随其后的下一行缩进一次。
  • unIndentedLinePattern - 如果一行匹配此模式,则不应更改其缩进,并且不应针对其他规则对其进行评估。

如果未为编程语言设置缩进规则,则当行以左括号结尾时,编辑器将缩进;当您键入右括号时,编辑器将取消缩进。此处的括号由 brackets 定义。

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

On 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。一个正则表达式,用于匹配光标上方一行的文本。

如果所有指定的属性都匹配,则认为该规则匹配,并且不会评估进一步的 onEnterRulesonEnterRule 可以指定以下操作

  • indent(必需)。none、indent、outdent、indentOutdent 之一。
    • none 表示新行将继承当前行的缩进。
    • indent 表示新行将相对于当前行缩进。
    • outdent 表示新行将相对于当前行取消缩进。
    • indentOutdent 表示将插入两个新行,一个缩进,第二个取消缩进。
  • appendText。一个字符串,将附加到新行之后和缩进之后。
  • removeText。要从新行的缩进中删除的字符数。