语义高亮指南

语义高亮是对语法高亮指南中描述的语法高亮的补充。Visual Studio Code 使用 TextMate 语法作为主要的标记化引擎。TextMate 语法以单个文件作为输入，并根据正则表达式表示的词法规则将其分解。

语义标记化允许语言服务器根据语言服务器对如何在项目上下文中解析符号的知识来提供额外的标记信息。主题可以选择使用语义标记来改进和完善语法的语法高亮。编辑器将语义标记的高亮应用于语法高亮之上。

以下是语义高亮可以添加的示例

没有语义高亮

有语义高亮

请注意根据语言服务符号理解的颜色差异

• 第 10 行：languageModes 被着色为参数
• 第 11 行：Range 和 Position 被着色为类，document 被着色为参数。
• 第 13 行：getFoldingRanges 被着色为函数。

语义标记提供程序

要实现语义高亮，语言扩展可以通过文档语言和/或文件名注册一个语义标记提供程序。当需要语义标记时，编辑器会向提供程序发出请求。

const tokenTypes = ['class', 'interface', 'enum', 'function', 'variable'];
const tokenModifiers = ['declaration', 'documentation'];
const legend = new vscode.SemanticTokensLegend(tokenTypes, tokenModifiers);

const provider: vscode.DocumentSemanticTokensProvider = {
  provideDocumentSemanticTokens(
    document: vscode.TextDocument
  ): vscode.ProviderResult<vscode.SemanticTokens> {
    // analyze the document and return semantic tokens

    const tokensBuilder = new vscode.SemanticTokensBuilder(legend);
    // on line 1, characters 1-5 are a class declaration
    tokensBuilder.push(
      new vscode.Range(new vscode.Position(1, 1), new vscode.Position(1, 5)),
      'class',
      ['declaration']
    );
    return tokensBuilder.build();
  }
};

const selector = { language: 'java', scheme: 'file' }; // register for all Java documents from the local file system

vscode.languages.registerDocumentSemanticTokensProvider(selector, provider, legend);

语义标记提供程序 API 有两种形式，以适应语言服务器的功能

• DocumentSemanticTokensProvider - 始终以完整文档作为输入。

  • provideDocumentSemanticTokens - 提供文档的所有标记。
  • provideDocumentSemanticTokensEdits - 提供文档的所有标记，作为对先前响应的增量。

• DocumentRangeSemanticTokensProvider - 仅对范围起作用。

  • provideDocumentRangeSemanticTokens - 提供文档范围的所有标记。

提供程序返回的每个标记都带有一个分类，该分类由标记类型、任意数量的标记修饰符和标记语言组成。

如上面的示例所示，提供程序在SemanticTokensLegend中命名它将使用的类型和修饰符。这允许provide API 将标记类型和修饰符作为图例的索引返回。

语义标记分类

语义标记提供程序的输出由标记组成。每个标记都有一个范围和一个标记分类，描述该标记代表哪种语法元素。可选地，如果该标记是嵌入语言的一部分，分类还可以命名一种语言。

为了描述语法元素的种类，使用了语义标记类型和修饰符。此信息类似于语法高亮指南中描述的 TextMate 范围，但我们希望提出一个专用且更清晰的分类系统。

VS Code 带有一组所有语义标记提供程序使用的标准语义标记类型和修饰符。尽管如此，语义标记提供程序可以自由定义新的类型和修饰符，并创建标准类型的子类型。

标准标记类型和修饰符

标准类型和修饰符涵盖了许多语言使用的常见概念。虽然每种语言可能对某些类型和修饰符使用不同的术语，但通过遵循标准分类，主题作者将能够定义跨语言工作的主题规则。

这些是 VS Code 预定义的标准语义标记类型和语义标记修饰符

标准标记类型

标准标记修饰符

除了标准类型和修饰符，VS Code 还定义了类型和修饰符到类似 TextMate 范围的映射。这在语义标记范围映射部分有介绍。

自定义标记类型和修饰符

如有必要，扩展可以通过其扩展的package.json中的semanticTokenTypes和semanticTokenModifiers贡献点声明新的类型和修饰符，或创建现有类型的子类型

{
  "contributes": {
    "semanticTokenTypes": [
      {
        "id": "templateType",
        "superType": "type",
        "description": "A template type."
      }
    ],
    "semanticTokenModifiers": [
      {
        "id": "native",
        "description": "Annotates a symbol that is implemented natively"
      }
    ]
  }
}

在上面的示例中，一个扩展声明了一个新的类型templateType和一个新的修饰符native。通过将type命名为超类型，type的主题样式规则也将应用于templateType

{
  "name": "Red Theme",
  "semanticTokenColors": {
    "type": "#ff0011"
  }
}

上面显示的semanticTokenColors值"#ff0011"适用于type及其所有子类型，包括templateType。

除了自定义标记类型，扩展还可以定义这些类型如何映射到 TextMate 范围。这在自定义映射部分有描述。请注意，自定义映射规则不会自动从超类型继承。相反，子类型需要重新定义映射，最好是更具体的范围。

启用语义高亮

是否计算和高亮语义标记由设置editor.semanticHighlighting.enabled决定。它可以有值true、false和configuredByTheme。

• true和false将为所有主题打开或关闭语义高亮。
• configuredByTheme是默认值，它让每个主题控制是否启用语义高亮。VS Code 附带的所有主题（例如，“Dark+”默认主题）默认都启用了语义高亮。

依赖于语义标记的语言扩展可以在其package.json中覆盖其语言的默认设置

{
  "configurationDefaults": {
    "[languageId]": {
      "editor.semanticHighlighting.enabled": true
    }
  }
}

主题

主题化是将颜色和样式分配给标记。主题化规则在颜色主题文件（JSON 格式）中指定。用户还可以在用户设置中自定义主题化规则。

颜色主题中的语义着色

颜色主题文件格式中添加了两个新属性，以支持基于语义标记的高亮显示。

属性semanticHighlighting定义了主题是否准备好使用语义标记进行高亮显示。默认情况下为 false，但我们鼓励所有主题启用它。当设置editor.semanticHighlighting.enabled设置为configuredByTheme时使用此属性。

属性semanticTokenColors允许主题定义新的着色规则，这些规则与语义标记提供程序发出的语义标记类型和修饰符匹配。

{
  "name": "Red Theme",
  "tokenColors": [
    {
      "scope": "comment",
      "settings": {
        "foreground": "#dd0000",
        "fontStyle": "italic"
      }
    }
  ],
  "semanticHighlighting": true,
  "semanticTokenColors": {
    "variable.readonly:java": "#ff0011"
  }
}

variable.readonly:java被称为选择器，其形式为(*|tokenType)(.tokenModifier)*(:tokenLanguage)?。

该值描述了规则匹配时的样式。它是一个字符串，表示前景色，或者是一个对象，形式为{ foreground: string, bold: boolean, italic: boolean, underline: boolean }或{ foreground: string, fontStyle: string }，如tokenColors中 TextMate 主题规则所用。

前景颜色需要遵循颜色格式中描述的颜色格式。不支持透明度。

以下是选择器和样式的其他示例

• "*.declaration": { "bold": true } // 所有声明均为粗体
• "class:java": { "foreground": "#0f0", "italic": true } // Java 中的类

如果没有规则匹配或者主题没有semanticTokenColors部分（但semanticHighlighting已启用），VS Code 会使用语义标记范围映射来评估给定语义标记的 TextMate 范围。该范围与主题tokenColors中的 TextMate 主题规则匹配。

语义标记范围映射

为了使语义高亮适用于未定义任何特定语义规则的主题，并作为自定义标记类型和修饰符的备用，VS Code 维护了一个从语义标记选择器到 TextMate 范围的映射。

如果主题启用了语义高亮，但没有包含给定语义标记的规则，则这些 TextMate 范围将用于查找 TextMate 主题规则。

预定义的 TextMate 范围映射

下表列出了当前预定义的映射。

自定义 TextMate 范围映射

该映射可以通过扩展在其package.json中的semanticTokenScopes贡献点进行扩展。

扩展这样做的用例有两个

• 定义自定义标记类型和标记修饰符的扩展提供 TextMate 范围作为备用，当主题没有为添加的语义标记类型或修饰符定义主题规则时

  {
    "contributes": {
      "semanticTokenScopes": [
        {
          "scopes": {
            "templateType": ["entity.name.type.template"]
          }
        }
      ]
    }
  }
  

• TextMate 语法的提供程序可以描述特定于语言的范围。这有助于包含特定于语言的主题规则的主题。

  {
    "contributes": {
      "semanticTokenScopes": [
        {
          "language": "typescript",
          "scopes": {
            "property.readonly": ["variable.other.constant.property.ts"]
          }
        }
      ]
    }
  }
  

试试看

我们有一个语义标记示例，它说明了如何创建语义标记提供程序。

范围检查器工具允许您探索源文件中存在的语义标记以及它们匹配的主题规则。要查看语义标记，请在 TypeScript 文件上使用内置主题（例如，Dark+）。