使用语言配置自定义编辑器行为

你可以通过使用语言配置来启用特定于语言的语法操作，从而在 Visual Studio 编辑器中实现自定义的语言特定语法。 与使用语言服务器相比，使用语言配置可以提高性能，因为它的所有操作都是本地操作。

什么是语言配置

Visual Studio 通过语言扩展为各种编程语言提供智能编辑功能。 语言配置补充了使用语言服务器协议 (LSP) 的服务器，并提供声明性数据，使 Visual Studio 编辑器能够做出格式设置、着色和完成决策，而不会延迟对 LSP 服务器进行异步查询。 声明性语言功能在配置文件中定义。 例如，与 Visual Studio 捆绑在一起的 HTML、CSS 和打字稿基本扩展可提供以下部分声明性语言功能：

• 语法突出显示
• 片段完成
• 括号匹配
• 自动添加结束括号
• 注释切换
• 自动缩进

Visual Studio 提供了为任何编程语言定义语言配置的扩展功能。 语言配置文件控制基本的编辑功能，例如注释切换、括号匹配和包围。

使用语言配置有助于：

• 用户输入时进行同步工作
• 简单性：带有正则表达式的短 JSON 文件比复杂的算法更容易维护
• 可移植性：在 Visual Studio Code 和 Visual Studio 之间不需要进行更改或只需进行极少量更改

此外，语言配置文件提供了一种简单的方法来扩展 Visual Studio，以通过易于阅读的 JSON 文件支持一些基本的重构功能。

向 Visual Studio 扩展添加语言配置支持

向 Visual Studio 扩展添加语言配置支持分为三个部分：

1. 创建 VSIX 项目
2. 创建语言配置文件
3. 添加语法文件
4. 更新 pkgdef 文件

您可以在语言配置示例中探索工作示例。

创建 VSIX 项目

要使用语言配置创建语言服务扩展，首先请确保为 VS 实例安装了 Visual Studio 扩展开发工作负载。

接下来，通过导航到文件>新建项目来创建一个新的 VSIX 项目，搜索“vsix”并查找 VSIX 项目：

创建语言配置文件

在制作自己的语言配置文件时，您可以选择要在 JSON 文件中加入哪些方面的内容。 例如，您可以选择支持注释切换、自动添加右括号或本节中描述的可用功能的任意组合。

要添加对扩展的支持，你首先需要创建一个语言配置文件。 文件名必须遵循以下标准：使用连字符分隔文件名中的单词，并确保以 language-configuration.json 结尾。

以下代码显示了示例语言配置文件。

{
    "comments": {
      "lineComment": "***",
      "blockComment": ["{*", "*}"]
    },
    "brackets": [
      ["@", "@"],
      ["#", "#"],
      ["$", "$"],
      ["(", ")"]
    ],
    "autoClosingPairs": [
      { "open": "{", "close": "}" },
      { "open": "@", "close": "@" },
      { "open": "#", "close": "#" },
      { "open": "$", "close": "$" },
      { "open": "(", "close": ")" },
      { "open": "'", "close": "'", "notIn": ["string", "comment"] },
      { "open": "\"", "close": "\"", "notIn": ["string"] },
    ],
    "autoCloseBefore": ";:.,=}])>` \n\t",
    "surroundingPairs": [
      ["@", "@"],
      ["#", "#"],
      ["$", "$"],
      ["[", "]"],
      ["(", ")"],
      ["'", "'"],
      ["\"", "\""],
      ["`", "`"]
    ],
    "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)",
    "indentationRules": {
      "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
      "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
    }
  }

配置设置

以下部分描述了语言配置文件中可用的设置。

注释切换

语言配置文件提供了两个用于注释切换的命令。 切换行注释和切换块注释。 您可以指定 comments.blockComment 和 comments.lineComment 来控制 Visual Studio 应如何注释掉行/块。

{
  "comments": {
    "lineComment": "//",
    "blockComment": ["/*", "*/"]
  }
}

当您按 Ctrl+K、Ctrl+C 时，此设置会影响 Visual Studio 文本编辑器的行为。

括号定义

当你将光标移动到此处定义的括号时，Visual Studio 会突出显示该括号及其匹配对。

{
  "brackets": [["{", "}"], ["[", "]"], ["(", ")"]]
}

Visual Studio 工具 > 选项对话框中的相关设置在文本编辑器、常规、显示中是启用大括号对着色复选框。

自动关闭

当您键入 ' 时，Visual Studio 会创建一对单引号并将光标放在中间：'|'。 本节定义了此类对。

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

在前面自动关闭

默认情况下，Visual Studio 仅在光标后面有空格时自动关闭对。 因此，当您在以下 JSX 代码中输入 { 时，将不会进行自动关闭：

const Component = () =>
  <div className={>
                  ^ Does not get autoclosed by default
  </div>

但是，此定义会替代该行为：

{
  "autoCloseBefore": ";:.,=}])>` \n\t"
}

现在，当您在 > 之前输入 { 时，Visual Studio 会使用 } 自动关闭它。

自动包围

当您在 Visual Studio 中选择一个范围并输入左括号时，Visual Studio 会用一对括号将所选内容括起来。 此功能称为自动包围，您可以在此处为特定语言定义自动包围对：

{
  "surroundingPairs": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"],
    ["'", "'"],
    ["\"", "\""],
    ["`", "`"]
  ]
}

Visual Studio 工具> 选项中的相关设置在文本编辑器、常规、显示中是键入引号或括号时自动包围所选内容复选框。

字词模式

wordPattern 定义编程语言中被视为字词的内容。 如果设置了 wordPattern，则代码建议功能会使用此设置来确定单词边界。

{
  "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)"
}

缩进规则

indentationRules 定义当您键入、粘贴和移动行时，或者当您使用 Ctrl+K、Ctrl+D（设置文档格式）和 Ctrl+K、Ctrl+F（格式选择）设置文本格式时，编辑器应如何调整当前行或下一行的缩进 。

{
  "indentationRules": {
    "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
    "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
  }
}

例如，如果 if (true) { 匹配 increaseIndentPattern，那么如果您在左括号 { 后按 Enter，则编辑器将自动缩进一次，您的代码最终将为：

if (true) {
  console.log();

除了 increaseIndentPattern 和 decreaseIndentPatter 之外，还有另外两个缩进规则：

• indentNextLinePattern - 如果一个行与此模式匹配，则仅应将其后的下一行缩进一次。
• unIndentedLinePattern- 如果某一行与此模式匹配，则不应更改其缩进，也不应根据其他规则对其进行评估。

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

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

属性设置

在扩展项目中，确保您的 language-configuration.json 文件具有以下属性设置：

Build Action = Content
Include in VSIX = True
Copy to output = Copy always 

（可选）添加语法文件

此外，您还可以添加 TextMate 语法文件来为语言提供语法着色。 TextMate 语法是正则表达式的结构化集合，并以 plist (XML) 或 JSON 文件形式编写。 请参阅语言语法。 如果您不提供特定于语言的语法文件，则使用内置的默认设置。

要添加自定义 TextMate 语法或主题文件，请执行下列步骤：

1. 在扩展内创建一个名为“Grammars”的文件夹（或者可以是您选择的任何名称）。

2. 在 Grammars 文件夹中，包含您想要提供自定义着色的任何 *.tmlanguage、*.plist、*.tmtheme 或 *.json 文件。

   提示

   .tmtheme 文件定义范围如何映射到 Visual Studio 分类（命名的颜色键）。 如需指导，您可以参考 %ProgramFiles(x86)%\Microsoft Visual Studio\<version>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg 目录中的全局 .tmtheme 文件。

创建 pkgdef 文件

接下来，创建 .pkgdef 文件。 .pkgdef 文件包含将以其他方式添加到系统注册表中的所有注册信息。 有关 pkgdef 文件的详细信息，请参阅注册 VSPackages 和什么是 pkgdef 文件？为什么要使用此文件？ 在 pkgdef 文件中，您应该具有 language-configuration.json 文件的路径和语言语法的路径。 LSP 等语言服务会请求编辑器内容类型并通过语言配置获取该类型。 此信息提供了可以与开发工具通信的服务器内部的语言特定智能。 当语言服务不存在时，语言配置引擎将回退到 TextMate 语法。 .pkgdef 文件应如下所示：

[$RootKey$\TextMate\Repositories]
"AspNetCoreRazor="$PackageFolder$\Grammars

// Defines where the language configuration file for a given
// grammar name is (value of the ScopeName tag in the tmlanguage file).
[$RootKey$\TextMate\LanguageConfiguration\GrammarMapping]
"text.aspnetcorerazor"="$PackageFolder$\language-configuration.json"

// Defines where the language configuration file for a given
// language name is (partial value of the content type name).
[$RootKey$\TextMate\LanguageConfiguration\ContentTypeMapping]
"RazorLSP"="$PackageFolder$\language-configuration.json"

[$RootKey$\TextMate\LanguageConfiguration\GrammarMapping]
"text.html.basic"="$PackageFolder$\html-language-configuration.json"
"source.js"="$PackageFolder$\javascript-language-configuration.json"
"source.css"="$PackageFolder$\css-language-configuration.json"
"source.cs"="$PackageFolder$\csharp-language-configuration.json

确保按如下方式设置 pkgdef 文件的属性：

Build Action = Content
Include in VSIX = True
Copy to output = Copy always 

为了使 Visual Studio 能够访问语言配置信息，请在 VSIX 包中包含 language-configuration 文件。 包含此文件意味着它将随 Visual Studio 扩展一起提供。 该文件可让 Visual Studio 知道语言配置可供使用。 要添加此文件，请编辑您的 vsixmanifest，以添加 PKGDEF def 文件，例如：

<Asset Type="Microsoft.VisualStudio.VsPackage" Path="Test.pkgdef"/> 

相关内容

• 语言服务器协议

• 语言配置示例