语法高亮指南

语法高亮确定在 Visual Studio Code 编辑器中显示的源代码的颜色和样式。它负责将 JavaScript 中的 if 或 for 等关键字与字符串、注释和变量名区分开来进行颜色化。

语法高亮有两个组成部分：

• 标记化：将文本分解为标记列表
• 主题化：使用主题或用户设置将标记映射到特定的颜色和样式

在深入了解细节之前，一个良好的开始是使用 作用域检查器 工具并探索源文件中存在的标记以及它们匹配的主题规则。要查看语义和语法标记，请在 TypeScript 文件上使用内置主题（例如，Dark+）。

标记化

文本标记化是关于将文本分解为段，并使用标记类型对每个段进行分类。

VS Code 的标记化引擎由 TextMate 语法 提供支持。TextMate 语法是正则表达式的结构化集合，并以 plist（XML）或 JSON 文件的形式编写。VS Code 扩展可以通过 grammars 贡献点贡献语法。

TextMate 标记化引擎在与渲染器相同的进程中运行，并且标记会在用户键入时更新。标记用于语法高亮，但也用于将源代码分类为注释、字符串、正则表达式区域。

从 1.43 版本开始，VS Code 还允许扩展通过 语义标记提供者 提供标记化。语义提供者通常由语言服务器实现，语言服务器对源文件有更深入的理解，并且可以在项目上下文中解析符号。例如，一个常量变量名可以在整个项目中使用常量高亮显示，而不仅仅是在其声明的地方。

基于语义标记的高亮显示被认为是基于 TextMate 的语法高亮显示的补充。语义高亮显示在语法高亮显示之上。由于语言服务器可能需要一段时间才能加载和分析项目，因此语义标记高亮显示可能会在短时间延迟后出现。

本文重点介绍基于 TextMate 的标记化。语义标记化和主题化在 语义高亮指南 中解释。

TextMate 语法

VS Code 使用 TextMate 语法 作为语法标记化引擎。它们最初是为了 TextMate 编辑器而发明的，但由于开源社区创建和维护了大量的语言包，因此已被许多其他编辑器和 IDE 采用。

TextMate 语法依赖于 Oniguruma 正则表达式，通常以 plist 或 JSON 形式编写。您可以在这里找到关于 TextMate 语法的良好介绍 这里，并且可以查看现有的 TextMate 语法以了解有关其工作原理的更多信息。

TextMate 标记和作用域

标记是属于同一程序元素的一个或多个字符。标记示例包括运算符，例如 + 和 *、变量名，例如 myVar、或字符串，例如 "my string"。

每个标记都与一个作用域相关联，该作用域定义了标记的上下文。作用域是一个用点分隔的标识符列表，用于指定当前标记的上下文。例如，JavaScript 中的 + 运算符具有作用域 keyword.operator.arithmetic.js。

主题将作用域映射到颜色和样式以提供语法高亮显示。TextMate 提供 常用作用域列表，许多主题都以这些作用域为目标。为了使您的语法尽可能广泛地得到支持，请尝试构建在现有作用域的基础上，而不是定义新的作用域。

作用域嵌套，因此每个标记也与一系列父作用域相关联。以下示例使用 作用域检查器 来显示简单 JavaScript 函数中 + 运算符的作用域层次结构。最具体的作用域列在顶部，更通用的父作用域列在下面

父作用域信息也用于主题化。当主题以作用域为目标时，所有具有该父作用域的标记都将被颜色化，除非主题还为其单独的作用域提供更具体的颜色化。

贡献基本语法

VS Code 支持 json TextMate 语法。这些语法是通过 grammars 贡献点 贡献的。

每个语法贡献都指定：语法适用的语言的标识符、语法标记的顶级作用域名称以及语法文件的相对路径。以下示例显示了虚构 abc 语言的语法贡献

{
  "contributes": {
    "languages": [
      {
        "id": "abc",
        "extensions": [".abc"]
      }
    ],
    "grammars": [
      {
        "language": "abc",
        "scopeName": "source.abc",
        "path": "./syntaxes/abc.tmGrammar.json"
      }
    ]
  }
}

语法文件本身由一个顶级规则组成。这通常被分成一个 patterns 部分，该部分列出程序的顶级元素，以及一个 repository 部分，该部分定义每个元素。语法中的其他规则可以使用 { "include": "#id" } 从 repository 中引用元素。

以下示例 abc 语法将字母 a、b 和 c 标记为关键字，并将括号嵌套标记为表达式。

{
  "scopeName": "source.abc",
  "patterns": [{ "include": "#expression" }],
  "repository": {
    "expression": {
      "patterns": [{ "include": "#letter" }, { "include": "#paren-expression" }]
    },
    "letter": {
      "match": "a|b|c",
      "name": "keyword.letter"
    },
    "paren-expression": {
      "begin": "\\(",
      "end": "\\)",
      "beginCaptures": {
        "0": { "name": "punctuation.paren.open" }
      },
      "endCaptures": {
        "0": { "name": "punctuation.paren.close" }
      },
      "name": "expression.group",
      "patterns": [{ "include": "#expression" }]
    }
  }
}

语法引擎将尝试连续地将 expression 规则应用于文档中的所有文本。对于像这样的简单程序

a
(
    b
)
x
(
    (
        c
        xyz
    )
)
(
a

以下示例语法生成以下作用域（从最具体的作用域到最不具体的作用域，从左到右列出）

a               keyword.letter, source.abc
(               punctuation.paren.open, expression.group, source.abc
    b           keyword.letter, expression.group, source.abc
)               punctuation.paren.close, expression.group, source.abc
x               source.abc
(               punctuation.paren.open, expression.group, source.abc
    (           punctuation.paren.open, expression.group, expression.group, source.abc
        c       keyword.letter, expression.group, expression.group, source.abc
        xyz     expression.group, expression.group, source.abc
    )           punctuation.paren.close, expression.group, expression.group, source.abc
)               punctuation.paren.close, expression.group, source.abc
(               punctuation.paren.open, expression.group, source.abc
a               keyword.letter, expression.group, source.abc

请注意，没有被任何规则匹配的文本，例如字符串 xyz，将包含在当前作用域中。文件末尾的最后一个括号是 expression.group 的一部分，即使没有匹配到 end 规则，因为在 end 规则之前找到了 end-of-document。

嵌入式语言

如果您的语法在父语言中包含嵌入式语言，例如 HTML 中的 CSS 样式块，您可以使用 embeddedLanguages 贡献点告诉 VS Code 将嵌入式语言视为与父语言不同的语言。这将确保括号匹配、注释和其他基本语言功能在嵌入式语言中按预期工作。

embeddedLanguages 贡献点将嵌入式语言中的作用域映射到顶级语言作用域。在以下示例中，meta.embedded.block.javascript 作用域中的任何标记都将被视为 JavaScript 内容

{
  "contributes": {
    "grammars": [
      {
        "path": "./syntaxes/abc.tmLanguage.json",
        "scopeName": "source.abc",
        "embeddedLanguages": {
          "meta.embedded.block.javascript": "javascript"
        }
      }
    ]
  }
}

现在，如果您尝试注释代码或触发一组标记为 meta.embedded.block.javascript 的标记内部的代码段，它们将获得正确的 // JavaScript 样式注释和正确的 JavaScript 代码段。

开发新的语法扩展

要快速创建新的语法扩展，请使用 VS Code 的 Yeoman 模板 运行 yo code 并选择 New Language 选项

Yeoman 将引导您完成一些基本问题以构建新的扩展。创建新语法的关键问题是

• Language id - 您的语言的唯一标识符。
• Language name - 您的语言的人类可读名称。
• Scope names - 您的语法的根 TextMate 作用域名称。

生成器假设您要为新语言定义新的语言和语法。如果您为现有语言创建语法，只需使用目标语言的信息填写这些信息，并确保从生成的 package.json 中删除 languages 贡献点。

回答完所有问题后，Yeoman 将创建一个具有以下结构的新扩展

请记住，如果您为 VS Code 已经知道的语言贡献语法，请确保从生成的 package.json 中删除 languages 贡献点。

转换现有的 TextMate 语法

yo code 还可以帮助将现有的 TextMate 语法转换为 VS Code 扩展。同样，从运行 yo code 并选择 Language extension 开始。当被问及现有语法文件时，请提供 .tmLanguage 或 .json TextMate 语法文件的完整路径

使用 YAML 编写语法

随着语法变得越来越复杂，以 json 格式编写语法可能会变得难以理解和维护。如果您发现自己正在编写复杂的正则表达式或需要添加注释来解释语法的各个方面，请考虑使用 yaml 来定义您的语法。

Yaml 语法与基于 json 的语法的结构完全相同，但允许您使用 yaml 的更简洁的语法，以及多行字符串和注释等功能。

VS Code 只能加载 json 语法，因此基于 yaml 的语法必须转换为 json。 js-yaml 包 和命令行工具使这变得很容易。

# Install js-yaml as a development only dependency in your extension
$ npm install js-yaml --save-dev

# Use the command-line tool to convert the yaml grammar to json
$ npx js-yaml syntaxes/abc.tmLanguage.yaml > syntaxes/abc.tmLanguage.json

注入语法

注入语法允许您扩展现有语法。注入语法是一种普通的 TextMate 语法，它被注入到现有语法中的特定作用域中。注入语法的示例应用

• 在注释中突出显示关键字，例如 TODO。
• 为现有语法添加更具体的作用域信息。
• 为 Markdown 围栏代码块添加新语言的突出显示。

创建一个基本的注入语法

注入语法通过 package.json 文件贡献，就像普通语法一样。但是，注入语法不指定 language，而是使用 injectTo 指定要将语法注入的一系列目标语言作用域。

在这个例子中，我们将创建一个简单的注入语法，它在 JavaScript 注释中将 TODO 突出显示为关键字。为了在 JavaScript 文件中应用我们的注入语法，我们在 injectTo 中使用 source.js 目标语言作用域。

{
  "contributes": {
    "grammars": [
      {
        "path": "./syntaxes/injection.json",
        "scopeName": "todo-comment.injection",
        "injectTo": ["source.js"]
      }
    ]
  }
}

语法本身是一个标准的 TextMate 语法，除了顶级的 injectionSelector 条目。injectionSelector 是一个作用域选择器，它指定应在哪些作用域中应用注入语法。在我们的例子中，我们希望在所有 // 注释中突出显示单词 TODO。使用 作用域检查器，我们发现 JavaScript 的双斜杠注释具有 comment.line.double-slash 作用域，因此我们的注入选择器是 L:comment.line.double-slash

{
  "scopeName": "todo-comment.injection",
  "injectionSelector": "L:comment.line.double-slash",
  "patterns": [
    {
      "include": "#todo-keyword"
    }
  ],
  "repository": {
    "todo-keyword": {
      "match": "TODO",
      "name": "keyword.todo"
    }
  }
}

注入选择器中的 L: 表示注入被添加到现有语法规则的左侧。这基本上意味着我们注入语法的规则将在任何现有语法规则之前应用。

嵌入式语言

注入语法还可以将其嵌入语言贡献给父语法。就像使用普通语法一样，注入语法可以使用 embeddedLanguages 将嵌入语言的作用域映射到顶级语言作用域。

例如，一个突出显示 JavaScript 字符串中的 SQL 查询的扩展程序，可以使用 embeddedLanguages 来确保标记为 meta.embedded.inline.sql 的字符串中的所有标记都被视为 SQL，以实现基本的语言功能，例如括号匹配和片段选择。

{
  "contributes": {
    "grammars": [
      {
        "path": "./syntaxes/injection.json",
        "scopeName": "sql-string.injection",
        "injectTo": ["source.js"],
        "embeddedLanguages": {
          "meta.embedded.inline.sql": "sql"
        }
      }
    ]
  }
}

标记类型和嵌入语言

对于注入语言的嵌入语言，还有一个额外的复杂之处：默认情况下，VS Code 将字符串中的所有标记视为字符串内容，并将具有注释的所有标记视为标记内容。由于括号匹配和自动闭合对等功能在字符串和注释中被禁用，如果嵌入语言出现在字符串或注释中，这些功能也会在嵌入语言中被禁用。

为了覆盖此行为，您可以使用 meta.embedded.* 作用域来重置 VS Code 对标记为字符串或注释内容的标记的标记。最好始终将嵌入语言包装在 meta.embedded.* 作用域中，以确保 VS Code 正确处理嵌入语言。

如果您无法将 meta.embedded.* 作用域添加到您的语法中，您可以选择在语法的贡献点中使用 tokenTypes 将特定作用域映射到内容模式。下面的 tokenTypes 部分确保 my.sql.template.string 作用域中的任何内容都被视为源代码

{
  "contributes": {
    "grammars": [
      {
        "path": "./syntaxes/injection.json",
        "scopeName": "sql-string.injection",
        "injectTo": ["source.js"],
        "embeddedLanguages": {
          "my.sql.template.string": "sql"
        },
        "tokenTypes": {
          "my.sql.template.string": "other"
        }
      }
    ]
  }
}

主题

主题化是指将颜色和样式分配给标记。主题化规则在颜色主题中指定，但用户可以在用户设置中自定义主题化规则。

TextMate 主题规则在 tokenColors 中定义，并且具有与常规 TextMate 主题相同的语法。每个规则都定义一个 TextMate 作用域选择器以及一个结果颜色和样式。

在评估标记的颜色和样式时，当前标记的作用域将与规则的选择器匹配，以找到每个样式属性（前景色、粗体、斜体、下划线）的最具体规则。

颜色主题指南 描述了如何创建颜色主题。语义标记的主题化在 语义突出显示指南 中解释。

作用域检查器

VS Code 的内置作用域检查器工具有助于调试语法和语义标记。它显示了文件当前位置处标记和语义标记的作用域，以及有关哪些主题规则适用于该标记的元数据。

从命令面板中使用 Developer: Inspect Editor Tokens and Scopes 命令或 创建键绑定 来触发作用域检查器。

{
  "key": "cmd+alt+shift+i",
  "command": "editor.action.inspectTMScopes"
}

作用域检查器显示以下信息

1. 当前标记。
2. 有关标记的元数据以及有关其计算外观的信息。如果您正在使用嵌入语言，这里重要的条目是 language 和 token type。
3. 当当前语言有语义标记提供程序可用，并且当前主题支持语义突出显示时，就会显示语义标记部分。它显示了当前的语义标记类型和修饰符，以及与语义标记类型和修饰符匹配的主题规则。
4. TextMate 部分显示了当前 TextMate 标记的作用域列表，最具体的作用域在顶部。它还显示了与作用域匹配的最具体的主题规则。这仅显示负责标记当前样式的主题规则，不会显示被覆盖的规则。如果存在语义标记，只有当主题规则与语义标记匹配的规则不同时，才会显示主题规则。