VSCode扩展自定义TextMate与语义语法高亮的样式配置方法

自定义TextMate作用域与语义令牌样式的实现方案 #

一、TextMate自定义作用域默认样式配置 #

直接在扩展的package.json中使用contributes.tokenColors贡献点配置，支持颜色、斜体、粗体、下划线等全量样式属性，配置默认全局生效，优先级低于用户自定义规则与第三方主题规则：

{
  "contributes": {
    "tokenColors": [
      {
        "scope": "your.custom.scope", // 替换为你的自定义TextMate作用域
        "settings": {
          "foreground": "#FF79C6", // 自定义颜色值
          "fontStyle": "italic bold" // 按需组合样式，不需要额外样式则填空字符串
        }
      }
    ]
  }
}

二、自定义语义令牌默认样式配置 #

首先确保你已经在contributes.semanticTokenTypes中完成自定义语义令牌的声明：

{
  "contributes": {
    "semanticTokenTypes": [
      {
        "id": "yourCustomToken", // 替换为语言服务器返回的语义令牌类型ID
        "superType": "variable", // 无匹配规则时的回退父类型
        "description": "自定义语义令牌说明"
      }
    ]
  }
}

之后有两种常用配置方式可选：

方式1：映射到TextMate作用域复用样式

通过contributes.semanticTokenScopes贡献点，将自定义语义令牌映射到已经配置好样式的TextMate作用域，无需重复编写样式规则，天然适配现有主题体系：

{
  "contributes": {
    "semanticTokenScopes": [
      {
        "language": "yourLangId", // 替换为你的语言ID
        "scopes": {
          "yourCustomToken": ["your.custom.scope"] // 语义令牌对应到目标TextMate作用域
        }
      }
    ]
  }
}

方式2：独立配置语义令牌专属样式

如果需要语义令牌使用和TextMate作用域不同的样式，可通过contributes.configurationDefaults配置语义令牌专属规则，还可以针对不同主题类型配置差异化样式，实现主题切换适配：

{
  "contributes": {
    "configurationDefaults": {
      "[yourLangId]": {
        // 针对你的语言默认开启语义高亮
        "editor.semanticHighlighting.enabled": true,
        "editor.semanticTokenColorCustomizations": {
          // 暗色主题默认样式
          "[Default Dark+]": {
            "rules": {
              "yourCustomToken": {
                "foreground": "#8BE9FD",
                "fontStyle": "italic"
              },
              // 支持带修饰符的令牌配置
              "yourCustomToken.readonly": {
                "fontStyle": "bold italic"
              }
            }
          },
          // 亮色主题默认样式
          "[Default Light+]": {
            "rules": {
              "yourCustomToken": {
                "foreground": "#0066CC",
                "fontStyle": "italic"
              }
            }
          }
        }
      }
    }
  }
}

可选方案：扩展自带专属主题 #

如果需要提供完整的定制化高亮体验，可在contributes.themes中注册自定义主题文件，在主题文件内统一配置tokenColors（TextMate作用域样式）与semanticHighlighting（语义令牌样式）规则，用户切换到该主题时即可生效。 #

注意事项 #

• 所有扩展侧配置的默认样式优先级均低于用户手动配置的editor.tokenColorCustomizations与editor.semanticTokenColorCustomizations规则，不会覆盖用户自定义设置。
• 可通过VSCode内置的令牌与作用域检查器验证规则是否正确匹配到目标令牌，检查器会显示对应令牌的匹配规则来源。

内容的提问来源于stack exchange，提问作者Dennis Müller