贡献点

贡献点 (Contribution Points) 是一组 JSON 声明，您需要在 package.json 扩展清单的 contributes 字段中进行配置。您的扩展通过注册贡献点来扩展 Visual Studio Code 中的各项功能。以下是所有可用贡献点的列表：

contributes.authentication

贡献一个身份验证提供程序。这将为您的提供程序设置一个激活事件，并将其显示在扩展的功能列表中。

{
  "contributes": {
    "authentication": [
      {
        "label": "Azure DevOps",
        "id": "azuredevops"
      }
    ]
  }
}

contributes.breakpoints

通常，调试器扩展也会包含一个 contributes.breakpoints 条目，扩展程序会在其中列出启用设置断点的语言文件类型。

{
  "contributes": {
    "breakpoints": [
      {
        "language": "javascript"
      },
      {
        "language": "javascriptreact"
      }
    ]
  }
}

contributes.chatInstructions

为 Copilot Chat 贡献指令文件。指令文件提供自定义指南，这些指南会自动包含在聊天请求中，以引导 Copilot 的行为。使用此贡献点可将可复用的指令与您的扩展捆绑在一起，例如编码规范、框架特定指南或领域特定规则。

当用户的聊天请求与指令的用例相关时，Copilot 会自动应用已贡献的指令。您无需手动附加它们。

每个条目都需要一个相对于扩展根目录的 Markdown 文件 path。您可以选择指定一个 when 子句来控制何时启用这些指令。请在 Markdown 文件本身内（而不是在贡献点中）指定 name 和 description 元数据。

{
  "contributes": {
    "chatInstructions": [
      {
        "path": "./prompts/textMateGuidelines.instructions.md"
      }
    ]
  }
}

您可以使用可选的 when 子句根据上下文有条件地启用指令。

{
  "contributes": {
    "chatInstructions": [
      {
        "path": "./prompts/textMateGuidelines.instructions.md",
        "when": "resourceExtname == .tmLanguage"
      }
    ]
  }
}

chatInstructions 属性

属性	类型	必需	描述
`path`	`字符串`	是	相对于扩展根目录的 Markdown 文件路径。该路径必须解析为扩展内部的位置。
`when`	`字符串`	否	一个 when 子句条件，该条件必须为真才能启用此条目。

请参阅 chatPromptFiles 贡献点，了解如何贡献可复用的提示词文件。

contributes.chatPromptFiles

为 Copilot Chat 贡献提示词文件。提示词文件是可复用的聊天提示词，用户可以在聊天中将其作为斜杠命令调用。使用此贡献点可将现成的提示词与您的扩展捆绑在一起。

每个条目都需要一个相对于扩展根目录的 Markdown 文件 path。您可以选择指定一个 when 子句来有条件地启用该提示词。请在 Markdown 文件本身内（而不是在贡献点中）指定 name 和 description 元数据。

{
  "contributes": {
    "chatPromptFiles": [
      {
        "path": "./prompts/reviewAndCreateIssue.prompt.md"
      }
    ]
  }
}

chatPromptFiles 属性

属性	类型	必需	描述
`path`	`字符串`	是	相对于扩展根目录的 Markdown 文件路径。该路径必须解析为扩展内部的位置。
`when`	`字符串`	否	一个 when 子句条件，该条件必须为真才能启用此条目。

请参阅 chatInstructions 贡献点，了解如何贡献可复用的指令文件。

contributes.chatSkills

为 Copilot Chat 贡献代理技能 (Agent Skills)。代理技能是指令、脚本和资源的文件夹，Copilot 在执行特定任务时如果相关，可以加载这些技能。使用此贡献点可将可复用的技能与您的扩展捆绑在一起。

每个条目都需要一个相对于扩展根目录的 SKILL.md 文件 path。SKILL.md 文件必须遵循代理技能规范，并且其 name 字段必须与父目录名称匹配。您可以选择指定一个 when 子句来有条件地启用该技能。

{
  "contributes": {
    "chatSkills": [
      {
        "path": "./skills/my-skill/SKILL.md"
      }
    ]
  }
}

chatSkills 属性

属性	类型	必需	描述
`path`	`字符串`	是	相对于扩展根目录的 `SKILL.md` 文件路径。该路径必须解析为扩展内部的位置，且父目录名称必须与 `SKILL.md` 中的 `name` 字段匹配。
`when`	`字符串`	否	一个 when 子句条件，该条件必须为真才能启用此条目。

有关所需的技能结构和 SKILL.md 格式，请参阅从扩展中贡献技能。

contributes.colors

贡献新的可定义主题的颜色。扩展可以在编辑器装饰器和状态栏中使用这些颜色。定义完成后，用户可以在 workspace.colorCustomization 设置中自定义颜色，用户主题也可以设置该颜色值。

{
  "contributes": {
    "colors": [
      {
        "id": "superstatus.error",
        "description": "Color for error message in the status bar.",
        "defaults": {
          "dark": "errorForeground",
          "light": "errorForeground",
          "highContrast": "#010203",
          "highContrastLight": "#feedc3"
        }
      }
    ]
  }
}

颜色默认值可以为浅色、深色和高对比度主题分别定义，可以是现有颜色的引用，也可以是十六进制颜色值。

扩展可以使用 ThemeColor API 消费新的和现有的主题颜色。

const errorColor = new vscode.ThemeColor('superstatus.error');

contributes.commands

为命令贡献 UI，包含标题以及（可选的）图标、类别和启用状态。启用状态通过 when 子句表示。默认情况下，命令显示在命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 中，但它们也可以显示在其他菜单中。

已贡献命令的呈现方式取决于所属菜单。例如，命令面板会在命令前加上其 category 前缀，以便于分组。然而，命令面板不显示图标，也不显示已禁用的命令。相比之下，编辑器上下文菜单显示禁用的项目，但不显示类别标签。

注意：当调用命令（通过键盘快捷键、命令面板、任何其他菜单或以编程方式）时，VS Code 将发出一个激活事件 onCommand:${command}。

注意：当使用来自产品图标的图标时，设置 light 和 dark 将禁用该图标。正确的语法是 "icon": "$(book)"。

命令示例

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": {
          "light": "path/to/light/icon.svg",
          "dark": "path/to/dark/icon.svg"
        }
      }
    ]
  }
}

请参阅命令扩展指南，了解有关在 VS Code 扩展中使用命令的更多信息。

commands extension point example

命令图标规范

尺寸： 图标应为 16x16，具有 1 像素的填充（图像为 14x14）并居中。
颜色： 图标应使用单一颜色。
格式： 建议图标使用 SVG 格式，但也接受任何图像文件类型。

command icons

contributes.configuration

贡献将暴露给用户的设置。用户将能够在设置编辑器中或直接通过编辑 settings.json 文件来设置这些配置选项。

此部分可以是一个代表单一设置类别的对象，也可以是代表多个设置类别的对象数组。如果存在多个设置类别，设置编辑器将为该扩展显示一个目录菜单，标题键将用作子菜单条目的名称。

配置示例

{
  "contributes": {
    "configuration": {
      "title": "Settings Editor Test Extension",
      "type": "object",
      "properties": {
        "settingsEditorTestExtension.booleanExample": {
          "type": "boolean",
          "default": true,
          "description": "Boolean Example"
        },
        "settingsEditorTestExtension.stringExample": {
          "type": "string",
          "default": "Hello World",
          "description": "String Example"
        }
      }
    }
  }
}

configuration extension point example

您可以使用 vscode.workspace.getConfiguration('myExtension') 从扩展中读取这些值。

配置架构

您的配置条目不仅用于在 JSON 编辑器中编辑设置时提供智能提示，还用于定义它们在设置 UI 中的显示方式。

settings UI screenshot with numbers

title

类别的 title 1️⃣️ 是用于该类别的标题。

{
  "configuration": {
    "title": "GitMagic"
  }
}

对于具有多个设置类别的扩展，如果其中一个类别的标题与扩展的显示名称相同，设置 UI 会将该类别视为“默认类别”，忽略该类别的 order 字段，并将其设置放置在主扩展标题下方。

对于 title 和 displayName 字段，像“Extension”、“Configuration”和“Settings”这样的词是多余的。

✔ "title": "GitMagic"
❌ "title": "GitMagic Extension"
❌ "title": "GitMagic Configuration"
❌ "title": "GitMagic Extension Configuration Settings"

properties

configuration 对象中的 properties 2️⃣ 将形成一个字典，其中键是设置 ID，值提供有关设置的更多信息。虽然一个扩展可以包含多个设置类别，但扩展的每个设置仍必须具有唯一的 ID。一个设置 ID 不能是另一个设置 ID 的完整前缀。

没有显式 order 字段的属性将在设置 UI 中按字典顺序显示（而不是按它们在清单中列出的顺序）。

设置标题

在设置 UI 中，多个字段将用于为每个设置构建显示标题。键中的大写字母用于指示单词分隔。

单类别和默认类别配置的显示标题

如果配置具有单一设置类别，或者类别标题与扩展的显示名称相同，那么对于该类别内的设置，设置 UI 将使用设置 ID 和扩展的 name 字段来确定显示标题。

例如，对于设置 ID gitMagic.blame.dateFormat 和扩展名称 authorName.gitMagic，由于设置 ID 的前缀与扩展名称的后缀匹配，因此设置 ID 中的 gitMagic 部分将被删除，显示为：“Blame: Date Format”。

多类别配置的显示标题

如果配置具有多个设置类别，并且该类别标题与扩展的显示名称不同，那么对于该类别内的设置，设置 UI 将使用设置 ID 和类别 id 字段来确定显示标题。

例如，对于设置 ID css.completion.completePropertyWithSemicolon 和类别 ID css，由于设置 ID 的前缀与类别 ID 的后缀匹配，因此设置 ID 中的 css 部分将在设置 UI 中删除，生成的设置为“Completion: Complete Property With Semicolon”。

配置属性架构

配置键使用 JSON Schema 的超集来定义。

description / markdownDescription

您的 description 3️⃣ 出现在标题之后、输入字段之前，布尔值除外（布尔值的说明用作复选框的标签）。6️⃣

{
  "gitMagic.blame.heatMap.enabled": {
    "description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
  }
}

如果您使用 markdownDescription 代替 description，您的设置说明将在设置 UI 中被解析为 Markdown。

{
  "gitMagic.blame.dateFormat": {
    "markdownDescription": "Specifies how to format absolute dates (e.g. using the `${date}` token) in gutter blame annotations. See the [Moment.js docs](https://moment.js.cn/docs/#/displaying/format/) for valid formats"
  }
}

对于 markdownDescription，若要添加换行符或多个段落，请使用字符串 \n\n 来分隔段落，而不是仅仅使用 \n。

type

number 4️⃣、string 5️⃣、boolean 6️⃣ 类型的条目可以在设置 UI 中直接编辑。

{
  "gitMagic.views.pageItemLimit": {
    "type": "number",
    "default": 20,
    "markdownDescription": "Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit"
  }
}

如果字符串设置在配置条目上设置了 "editPresentation": "multilineText"，则可以使用多行文本输入进行渲染。

对于 boolean 条目，markdownDescription（如果未指定，则为 description）将用作复选框旁边的标签。

{
  "gitMagic.blame.compact": {
    "type": "boolean",
    "description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
  }
}

某些 object 和 array 类型设置将在设置 UI 中渲染。简单的 number、string 或 boolean 数组将渲染为可编辑列表。具有 string、number、integer 和/或 boolean 类型属性的对象将渲染为可编辑的键值网格。对象设置还应将 additionalProperties 设置为 false，或设置一个具有适当 type 属性的对象，以便在 UI 中渲染。

如果 object 或 array 类型设置还包含其他类型（如嵌套对象、数组或 null），则该值将不会在设置 UI 中渲染，只能通过直接编辑 JSON 来修改。用户将看到一个在 settings.json 中编辑的链接，如上面的截图中所示。8️⃣

order

类别和这些类别内的设置都可以使用整数 order 类型属性，该属性指定了它们相对于其他类别和/或设置应如何排序的参考。

如果两个类别都有 order 属性，编号较小的类别排在前面。如果没有为类别提供 order 属性，它将出现在赋予了该属性的类别之后。

如果同一类别内的两个设置都有 order 属性，编号较小的设置排在前面。如果同一类别内的另一个设置没有 order 属性，它将出现在赋予了该属性的设置之后。

如果两个类别具有相同的 order 属性值，或者同一类别内的两个设置具有相同的 order 属性值，它们将在设置 UI 中按字典顺序递增排序。

enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels

如果您在 enum 7️⃣ 属性下提供了项目数组，设置 UI 将渲染一个这些项目的下拉菜单。

您还可以提供一个 enumDescriptions 属性（一个与 enum 属性长度相同的字符串数组）。enumDescriptions 属性在设置 UI 的下拉菜单底部为每个 enum 项目提供相应的说明。
您还可以使用 markdownEnumDescriptions 代替 enumDescriptions，说明将被解析为 Markdown。markdownEnumDescriptions 的优先级高于 enumDescriptions。
要自定义设置 UI 中的下拉选项名称，可以使用 enumItemLabels。

示例

{
  "settingsEditorTestExtension.enumSetting": {
    "type": "string",
    "enum": ["first", "second", "third"],
    "markdownEnumDescriptions": [
      "The *first* enum",
      "The *second* enum",
      "The *third* enum"
    ],
    "enumItemLabels": ["1st", "2nd", "3rd"],
    "default": "first",
    "description": "Example setting with an enum"
  }
}

settings UI screenshot of example enum setting above

deprecationMessage / markdownDeprecationMessage

如果您设置了 deprecationMessage 或 markdownDeprecationMessage，该设置将带有警告下划线并显示您指定的消消息。此外，除非用户进行了配置，否则该设置将从设置 UI 中隐藏。如果您设置了 markdownDeprecationMessage，markdown 不会在设置悬停提示或问题视图中渲染。如果您同时设置了这两个属性，deprecationMessage 将显示在悬停提示和问题视图中，而 markdownDeprecationMessage 将作为 Markdown 在设置 UI 中渲染。

示例

{
  "json.colorDecorators.enable": {
    "type": "boolean",
    "description": "Enables or disables color decorators",
    "markdownDeprecationMessage": "**Deprecated**: Please use `#editor.colorDecorators#` instead.",
    "deprecationMessage": "Deprecated: Please use editor.colorDecorators instead."
  }
}

其他 JSON Schema 属性

您可以使用任何验证 JSON Schema 属性来描述配置值的其他约束：

default：用于定义属性的默认值。
minimum 和 maximum：用于限制数值。
maxLength, minLength：用于限制字符串长度。
pattern：用于将字符串限制为给定的正则表达式。
patternErrorMessage：当模式不匹配时，提供定制的错误消息。
format：用于将字符串限制为众所周知的格式，例如 date、time、ipv4、email 和 uri。
maxItems, minItems：用于限制数组长度。
editPresentation：用于控制设置编辑器中字符串设置渲染为单行输入框还是多行文本区域。

不支持的 JSON Schema 属性

以下属性在配置部分不支持：

$ref 和 definition：配置架构需要是自包含的，不能对聚合的设置 JSON 架构文档的样子做出假设。

有关这些功能及其他功能的更多详细信息，请参阅 JSON Schema 参考。

scope

配置设置可以具有以下作用域之一：

application - 应用于所有 VS Code 实例，且只能在用户设置中配置的设置。
machine - 只能在用户设置或远程设置中设置的机器特定设置。例如，不应在机器间共享的安装路径。这些设置的值不会被同步。
machine-overridable - 可以被工作区或文件夹设置覆盖的机器特定设置。这些设置的值不会被同步。
window - 可在用户、工作区或远程设置中配置的窗口（实例）特定设置。
resource - 应用于文件和文件夹的资源设置，可以在所有设置级别（包括文件夹设置）中进行配置。
language-overridable - 可在语言级别覆盖的资源设置。

配置作用域决定了何时通过设置编辑器向用户提供设置，以及该设置是否适用。如果未声明 scope，默认值为 window。

以下是来自内置 Git 扩展的配置作用域示例：

{
  "contributes": {
    "configuration": {
      "title": "Git",
      "properties": {
        "git.alwaysSignOff": {
          "type": "boolean",
          "scope": "resource",
          "default": false,
          "description": "%config.alwaysSignOff%"
        },
        "git.ignoredRepositories": {
          "type": "array",
          "default": [],
          "scope": "window",
          "description": "%config.ignoredRepositories%"
        },
        "git.autofetch": {
          "type": ["boolean", "string"],
          "enum": [true, false, "all"],
          "scope": "resource",
          "markdownDescription": "%config.autofetch%",
          "default": false,
          "tags": ["usesOnlineServices"]
        }
      }
    }
  }
}

您可以看到 git.alwaysSignOff 具有 resource 作用域，可以按用户、工作区或文件夹设置，而具有 window 作用域的忽略仓库列表则更全局地应用于 VS Code 窗口或工作区（可能是多根工作区）。

ignoreSync

您可以将 ignoreSync 设置为 true 以防止该设置与用户的设置同步。这对于非特定于用户的设置很有用。例如，remoteTunnelAccess.machineName 设置并非特定于用户，不应同步。请注意，如果您将 scope 设置为 machine 或 machine-overridable，则无论 ignoreSync 的值如何，该设置都不会同步。

{
  "contributes": {
    "configuration": {
      "properties": {
        "remoteTunnelAccess.machineName": {
          "type": "string",
          "default": "",
          "ignoreSync": true
        }
      }
    }
  }
}

链接到设置

您可以使用 markdown 类型属性中的特殊语法：`#target.setting.id#`，插入指向另一个设置的链接，该链接在设置 UI 中将呈现为可点击的链接。这适用于 markdownDescription、 markdownEnumDescriptions 和 markdownDeprecationMessage。示例：

  "files.autoSaveDelay": {
    "markdownDescription": "Controls the delay in ms after which a dirty editor is saved automatically. Only applies when `#files.autoSave#` is set to `afterDelay`.",
    // ...
  }

在设置 UI 中，这呈现为：

setting link example

contributes.configurationDefaults

为其他已注册的配置贡献默认值，并覆盖它们的默认值。

以下示例覆盖了 files.autoSave 设置的默认行为，使其在焦点更改时自动保存文件。

"configurationDefaults": {
      "files.autoSave": "onFocusChange"
}

您还可以为所提供的语言贡献默认编辑器配置。例如，以下代码片段为 markdown 语言贡献了默认编辑器配置：

{
  "contributes": {
    "configurationDefaults": {
      "[markdown]": {
        "editor.wordWrap": "on",
        "editor.quickSuggestions": {
          "comments": "off",
          "strings": "off",
          "other": "off"
        }
      }
    }
  }
}

contributes.customEditors

customEditors 贡献点是您的扩展告知 VS Code 其提供的自定义编辑器的方式。例如，VS Code 需要知道您的自定义编辑器适用于哪些文件类型，以及如何在任何 UI 中识别您的自定义编辑器。

以下是自定义编辑器扩展示例的基本 customEditor 贡献：

"contributes": {
  "customEditors": [
    {
      "viewType": "catEdit.catScratch",
      "displayName": "Cat Scratch",
      "selector": [
        {
          "filenamePattern": "*.cscratch"
        }
      ],
      "priority": "default"
    }
  ]
}

customEditors 是一个数组，因此您的扩展可以贡献多个自定义编辑器。

viewType - 自定义编辑器的唯一标识符。

这是 VS Code 将 package.json 中的自定义编辑器贡献与代码中实现的自定义编辑器关联起来的方式。它在所有扩展中必须是唯一的，因此请确保使用对于您的扩展唯一的名称，例如 "viewType": "myAmazingExtension.svgPreview"，而不是 "preview" 这种通用名称。
displayName - 在 VS Code UI 中标识自定义编辑器的名称。

显示名称在 VS Code UI（例如视图：重新打开方式下拉菜单）中向用户显示。
selector - 指定自定义编辑器对哪些文件处于活动状态。

selector 是一个或多个 glob 模式的数组。这些 glob 模式与文件名匹配，以确定自定义编辑器是否可用于它们。filenamePattern（如 *.png）将为所有 PNG 文件启用自定义编辑器。

您还可以创建与文件或目录名匹配的更具体的模式，例如 **/translations/*.json。
priority - (可选) 指定何时使用自定义编辑器。

priority 控制资源打开时何时使用自定义编辑器。可能的值为：
- "default" - 尝试为与自定义编辑器的 selector 匹配的每个文件使用该自定义编辑器。如果给定文件有多个自定义编辑器，用户将必须选择他们想要使用的那个。
- "option" - 默认不使用该自定义编辑器，但允许用户切换到它或将其配置为默认编辑器。

您可以在自定义编辑器扩展指南中了解更多信息。

contributes.debuggers

向 VS Code 贡献一个调试器。调试器贡献具有以下属性：

type 是一个唯一 ID，用于在启动配置中标识此调试器。
label 是此调试器在 UI 中对用户可见的名称。
program 是实现 VS Code 调试协议的调试适配器的路径，用于对接真实的调试器或运行时。
runtime：如果调试适配器的路径不是可执行文件，而是需要运行时。
configurationAttributes 是此调试器特定的启动配置参数架构。请注意，JSON 架构结构 $ref 和 definition 不受支持。
initialConfigurations 列出了用于填充初始 launch.json 的启动配置。
configurationSnippets 列出了在编辑 launch.json 时通过 IntelliSense 可用的启动配置。
variables 引入了替换变量，并将它们绑定到调试器扩展实现的命令。
languages：调试扩展可被视为“默认调试器”的语言。

调试器示例

{
  "contributes": {
    "debuggers": [
      {
        "type": "node",
        "label": "Node Debug",

        "program": "./out/node/nodeDebug.js",
        "runtime": "node",

        "languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"],

        "configurationAttributes": {
          "launch": {
            "required": ["program"],
            "properties": {
              "program": {
                "type": "string",
                "description": "The program to debug."
              }
            }
          }
        },

        "initialConfigurations": [
          {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "program": "${workspaceFolder}/app.js"
          }
        ],

        "configurationSnippets": [
          {
            "label": "Node.js: Attach Configuration",
            "description": "A new configuration for attaching to a running node program.",
            "body": {
              "type": "node",
              "request": "attach",
              "name": "${2:Attach to Port}",
              "port": 9229
            }
          }
        ],

        "variables": {
          "PickProcess": "extension.node-debug.pickNodeProcess"
        }
      }
    ]
  }
}

有关如何集成 debugger 的完整演练，请前往调试器扩展。

contributes.grammars

为语言贡献 TextMate 语法。您必须提供此语法适用的 language、语法的 TextMate scopeName 以及文件路径。

注意：包含语法的文件的格式可以是 JSON（文件名以 .json 结尾）或 XML plist 格式（所有其他文件）。

语法示例

{
  "contributes": {
    "grammars": [
      {
        "language": "markdown",
        "scopeName": "text.html.markdown",
        "path": "./syntaxes/markdown.tmLanguage.json",
        "embeddedLanguages": {
          "meta.embedded.block.frontmatter": "yaml"
        }
      }
    ]
  }
}

请参阅语法高亮指南，了解有关如何注册与语言关联的 TextMate 语法以获得语法高亮的更多信息。

grammars extension point example

contributes.icons

通过 ID 贡献一个新图标，以及一个默认图标。该图标 ID 随后可由扩展（或任何依赖该扩展的其他扩展）在任何可以使用 ThemeIcon 的地方使用，即 new ThemeIcon("iconId")、Markdown 字符串 ($(iconId)) 以及某些贡献点中的图标。

{
  "contributes": {
    "icons": {
      "distro-ubuntu": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E001"
        }
      },
      "distro-fedora": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E002"
        }
      }
    }
  }
}

contributes.iconThemes

向 VS Code 贡献一个文件图标主题。文件图标显示在文件名旁边，指示文件类型。

您必须指定一个 id（用于设置中）、一个标签以及指向文件图标定义文件的路径。

文件图标主题示例

{
  "contributes": {
    "iconThemes": [
      {
        "id": "my-cool-file-icons",
        "label": "Cool File Icons",
        "path": "./fileicons/cool-file-icon-theme.json"
      }
    ]
  }
}

请参阅文件图标主题指南，了解如何创建文件图标主题。

contributes.jsonValidation

为特定类型的 json 文件贡献验证架构。url 值可以是包含在扩展中的架构文件的本地路径，也可以是远程服务器 URL，例如 json 架构存储。

{
  "contributes": {
    "jsonValidation": [
      {
        "fileMatch": ".jshintrc",
        "url": "https://json.schemastore.org/jshintrc"
      }
    ]
  }
}

contributes.keybindings

贡献一个快捷键绑定规则，定义用户按下组合键时应调用的命令。请参阅快捷键绑定主题，其中详细解释了快捷键绑定。

贡献快捷键绑定将导致“默认键盘快捷方式”显示您的规则，并且该命令的每个 UI 表示形式现在都将显示您添加的快捷键绑定。当然，当用户按下该组合键时，命令也会被调用。

注意：由于 VS Code 在 Windows、macOS 和 Linux 上运行，而修饰键有所不同，因此您可以使用 "key" 设置默认组合键，并使用特定平台将其覆盖。

注意：当调用命令（通过快捷键绑定或从命令面板）时，VS Code 将发出一个激活事件 onCommand:${command}。

快捷键绑定示例

定义在 Windows 和 Linux 下的 Ctrl+F1 以及在 macOS 下的 Cmd+F1 触发 "extension.sayHello" 命令。

{
  "contributes": {
    "keybindings": [
      {
        "command": "extension.sayHello",
        "key": "ctrl+f1",
        "mac": "cmd+f1",
        "when": "editorTextFocus"
      }
    ]
  }
}

keybindings extension point example

contributes.languages

贡献编程语言定义。这将引入一种新语言，或者丰富 VS Code 对某种语言的理解。

contributes.languages 的主要作用是：

定义一个可以在 VS Code API 的其他部分重复使用的 languageId，例如 vscode.TextDocument.languageId 和 onLanguage 激活事件。
- 您可以使用 aliases 字段贡献一个人类可读的名称。列表中的第一项将用作人类可读的标签。
将文件扩展名 (extensions)、文件名 (filenames)、文件名 glob 模式 (filenamePatterns)、以特定行开头的文件（例如 hashbang）(firstLine) 以及 mimetypes 关联到该 languageId。
为贡献的语言贡献一组声明式语言特性。在语言配置指南中了解有关可配置编辑特性的更多信息。
贡献一个图标，如果主题不包含该语言的图标，该图标可在文件图标主题中使用。

语言示例

{
  "contributes": {
    "languages": [
      {
        "id": "python",
        "extensions": [".py"],
        "aliases": ["Python", "py"],
        "filenames": [],
        "firstLine": "^#!/.*\\bpython[0-9.-]*\\b",
        "configuration": "./language-configuration.json",
        "icon": {
          "light": "./icons/python-light.png",
          "dark": "./icons/python-dark.png"
        }
      }
    ]
  }
}

contributes.menus

将命令的菜单项贡献到编辑器或资源管理器。菜单项定义包含选择该菜单项时应调用的命令，以及显示该项的条件。后者通过 when 子句定义，它使用快捷键绑定的 when 子句上下文。

command 属性指示选择菜单项时要运行的命令。submenu 属性指示在此位置渲染哪个子菜单。

在声明 command 菜单项时，也可以使用 alt 属性定义替代命令。它将在按住 Alt 键打开菜单时显示并被调用。在 Windows 和 Linux 上，Shift 键也可以实现此功能，这在 Alt 键会触发窗口菜单栏的情况下很有用。

最后，group 属性定义菜单项的排序和分组。navigation 组很特别，因为它总是被排序到菜单的顶部/开头。

注意：when 子句适用于菜单，enablement 子句适用于命令。enablement 适用于所有菜单甚至快捷键绑定，而 when 仅适用于单个菜单。

目前，扩展开发者可以贡献到：

commandPalette - 全局命令面板
comments/comment/title - 评论标题菜单栏
comments/comment/context - 评论上下文菜单
comments/commentThread/title - 评论线程标题菜单栏
comments/commentThread/context - 评论线程上下文菜单
debug/callstack/context - 调试调用堆栈视图上下文菜单
debug/callstack/context 组 inline - 调试调用堆栈视图内联操作
debug/toolBar - 调试视图工具栏
debug/variables/context - 调试变量视图上下文菜单
editor/context - 编辑器上下文菜单
editor/lineNumber/context - 编辑器行号上下文菜单
editor/title - 编辑器标题菜单栏
editor/title/context - 编辑器标题上下文菜单
editor/title/run - 编辑器标题菜单栏上的运行子菜单
explorer/context - 资源管理器视图上下文菜单
extension/context - 扩展视图上下文菜单
file/newFile - “文件”菜单和欢迎页中的“新建文件”项
interactive/toolbar - 交互式窗口工具栏
interactive/cell/title - 交互式窗口单元格标题菜单栏
notebook/toolbar - 笔记本工具栏
notebook/cell/title - 笔记本单元格标题菜单栏
notebook/cell/execute - 笔记本单元格执行菜单
scm/title - SCM 标题菜单
scm/resourceGroup/context - SCM 资源组菜单
scm/resourceFolder/context - SCM 资源文件夹菜单
scm/resourceState/context - SCM 资源菜单
scm/change/title - SCM 变更标题菜单
scm/repository - SCM 仓库菜单
scm/sourceControl - SCM 源代码管理菜单
terminal/context - 终端上下文菜单
terminal/title/context - 终端标题上下文菜单
testing/item/context - 测试资源管理器项上下文菜单
testing/item/gutter - 测试项的行号槽装饰菜单
timeline/title - 时间轴视图标题菜单栏
timeline/item/context - 时间轴视图项上下文菜单
touchBar - macOS 触控栏
view/title - 视图标题菜单
view/item/context - 视图项上下文菜单
webview/context - 任何 webview 上下文菜单
任何已贡献子菜单

注意 1：当从（上下文）菜单调用命令时，VS Code 会尝试推断当前选定的资源，并在调用命令时将其作为参数传递。例如，资源管理器内的菜单项会传递所选资源的 URI，而编辑器内的菜单项会传递文档的 URI。

注意 2：贡献到 editor/lineNumber/context 的菜单项的命令也会被传递行号。此外，这些项可以在其 when 子句中引用 editorLineNumber 上下文键，例如通过使用 in 或 not in 运算符来针对扩展管理的数组类型上下文键进行测试。

除了标题外，已贡献命令还可以指定图标，当调用菜单项以按钮形式表示（例如在标题菜单栏上）时，VS Code 会显示该图标。

这是一个命令菜单项：

{
  "contributes": {
    "menus": {
      "editor/title": [
        {
          "when": "resourceLangId == markdown",
          "command": "markdown.showPreview",
          "alt": "markdown.showPreviewToSide",
          "group": "navigation"
        }
      ]
    }
  }
}

menus extension point example

同样，这是一个添加到特定视图的命令菜单项。下面的示例贡献到了像终端这样的任意视图：

{
  "contributes": {
    "menus": {
      "view/title": [
        {
          "command": "terminalApi.sendText",
          "when": "view == terminal",
          "group": "navigation"
        }
      ]
    }
  }
}

Adding a menu entry to view/title with view == terminal will result in an action in the panel when the terminal is open

这是一个子菜单项：

{
  "contributes": {
    "menus": {
      "scm/title": [
        {
          "submenu": "git.commit",
          "group": "2_main@1",
          "when": "scmProvider == git"
        }
      ]
    }
  }
}

menus extension point example (submenu)

在 package.json 中注册命令时，它们将自动显示在命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 中。为了允许更多地控制命令可见性，可以使用 commandPalette 菜单项。它允许您定义 when 条件来控制命令是否应在命令面板中可见。

下面的代码片段使“Hello World”命令仅在编辑器中选择了某些内容时在命令面板中可见：

{
  "commands": [
    {
      "command": "extension.sayHello",
      "title": "Hello World"
    }
  ],
  "menus": {
    "commandPalette": [
      {
        "command": "extension.sayHello",
        "when": "editorHasSelection"
      }
    ]
  }
}

组的排序

菜单项可以分类到组中。它们按字典顺序排序，并遵循以下默认规则/顺序。您可以将菜单项添加到这些组，或者在组之间、下方或上方添加新的菜单项组。

编辑器上下文菜单具有以下默认组：

navigation - navigation 组在所有情况下都排在第一位。
1_modification - 此组紧随其后，包含修改代码的命令。
9_cutcopypaste - 倒数第二个默认组，包含基本的编辑命令。
z_commands - 最后一个默认组，包含用于打开命令面板的条目。

Menu Group Sorting

资源管理器上下文菜单具有以下默认组：

navigation - 与 VS Code 导航相关的命令。此组在所有情况下都排在第一位。
2_workspace - 与工作区操作相关的命令。
3_compare - 与在差异编辑器中比较文件相关的命令。
4_search - 与搜索视图中的搜索相关的命令。
5_cutcopypaste - 与文件的剪切、复制和粘贴相关的命令。
6_copypath - 与复制文件路径相关的命令。
7_modification - 与文件修改相关的命令。

编辑器选项卡上下文菜单具有以下默认组：

1_close - 与关闭编辑器相关的命令。
3_preview - 与固定编辑器相关的命令。

编辑器标题菜单具有以下默认组：

navigation - 与导航相关的命令。
1_run - 与运行和调试编辑器相关的命令。
1_diff - 与处理差异编辑器相关的命令。
3_open - 与打开编辑器相关的命令。
5_close - 与关闭编辑器相关的命令。

navigation 和 1_run 显示在主要编辑器标题区域。其他组显示在次要区域（在 ... 菜单下）。

终端选项卡上下文菜单具有以下默认组：

1_create - 与创建终端相关的命令。
3_run - 与在终端中运行/执行某些内容相关的命令。
5_manage - 与管理终端相关的命令。
7_configure - 与终端配置相关的命令。

终端上下文菜单具有以下默认组：

1_create - 与创建终端相关的命令。
3_edit - 与操作文本、选择内容或剪贴板相关的命令。
5_clear - 与清除终端相关的命令。
7_kill - 与关闭/终止终端相关的命令。
9_config - 与终端配置相关的命令。

时间轴视图项上下文菜单具有以下默认组：

inline - 重要或经常使用的时间轴项命令。渲染为工具栏。
1_actions - 与处理时间轴项相关的命令。
5_copy - 与复制时间轴项信息相关的命令。

扩展视图上下文菜单具有以下默认组：

1_copy - 与复制扩展信息相关的命令。
2_configure - 与配置扩展相关的命令。

组内排序

组内的顺序取决于标题或 order 属性。菜单项的组内顺序通过在组标识符后附加 @<number> 来指定，如下所示：

{
  "editor/title": [
    {
      "when": "editorHasSelection",
      "command": "extension.Command",
      "group": "myGroup@1"
    }
  ]
}

contributes.problemMatchers

贡献问题匹配器模式。这些贡献既适用于输出面板运行程序，也适用于终端运行程序。以下是在扩展中为 gcc 编译器贡献问题匹配器的示例：

{
  "contributes": {
    "problemMatchers": [
      {
        "name": "gcc",
        "owner": "cpp",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      }
    ]
  }
}

此问题匹配器现在可以通过名称引用 $gcc 在 tasks.json 文件中使用。示例如下：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "gcc",
      "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"],
      "problemMatcher": "$gcc"
    }
  ]
}

另请参阅：定义问题匹配器

contributes.problemPatterns

贡献命名的问题模式，可在问题匹配器中使用（见上文）。

contributes.productIconThemes

向 VS Code 贡献一个产品图标主题。产品图标是 VS Code 中除文件图标和从扩展贡献的图标之外的所有图标。

您必须指定一个 id（用于设置中）、一个标签以及指向图标定义文件的路径。

产品图标主题示例

{
  "contributes": {
    "productIconThemes": [
      {
        "id": "elegant",
        "label": "Elegant Icon Theme",
        "path": "./producticons/elegant-product-icon-theme.json"
      }
    ]
  }
}

请参阅产品图标主题指南，了解如何创建产品图标主题。

contributes.resourceLabelFormatters

贡献资源标签格式化程序，指定在工作台中到处显示 URI 的方式。例如，这是扩展如何为方案为 remotehub 的 URI 贡献格式化程序：

{
  "contributes": {
    "resourceLabelFormatters": [
      {
        "scheme": "remotehub",
        "formatting": {
          "label": "${path}",
          "separator": "/",
          "workspaceSuffix": "GitHub"
        }
      }
    ]
  }
}

这意味着所有方案为 remotehub 的 URI 将仅通过显示 URI 的 path 段来渲染，分隔符将为 /。具有 remotehub URI 的工作区在其标签中将具有 GitHub 后缀。

contributes.semanticTokenModifiers

贡献新的语义标记修饰符，可通过主题规则进行高亮显示。

{
  "contributes": {
    "semanticTokenModifiers": [
      {
        "id": "native",
        "description": "Annotates a symbol that is implemented natively"
      }
    ]
  }
}

请参阅语义高亮指南，详细了解语义高亮。

contributes.semanticTokenScopes

作为后备方案或支持特定语言的主题，贡献语义标记类型和修饰符与范围之间的映射。

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

请参阅语义高亮指南，详细了解语义高亮。

contributes.semanticTokenTypes

贡献新的语义标记类型，可通过主题规则进行高亮显示。

{
  "contributes": {
    "semanticTokenTypes": [
      {
        "id": "templateType",
        "superType": "type",
        "description": "A template type."
      }
    ]
  }
}

请参阅语义高亮指南，详细了解语义高亮。

contributes.snippets

为特定语言贡献代码片段。language 属性是语言标识符，path 是片段文件的相对路径，该文件定义了 VS Code 代码片段格式的片段。

下面的示例演示了如何为 Go 语言添加代码片段。

{
  "contributes": {
    "snippets": [
      {
        "language": "go",
        "path": "./snippets/go.json"
      }
    ]
  }
}

contributes.submenus

贡献一个子菜单作为占位符，菜单项可以贡献到该占位符上。子菜单需要一个 label 才能在父菜单中显示。

除了标题外，命令还可以定义图标，VS Code 将在编辑器标题菜单栏中显示这些图标。

子菜单示例

{
  "contributes": {
    "submenus": [
      {
        "id": "git.commit",
        "label": "Commit"
      }
    ]
  }
}

submenus extension point example

contributes.taskDefinitions

贡献并定义一个对象字面量结构，从而唯一标识系统中的贡献任务。任务定义至少具有一个 type 属性，但通常会定义其他属性。例如，代表 package.json 文件中脚本的任务的任务定义如下所示：

{
  "taskDefinitions": [
    {
      "type": "npm",
      "required": ["script"],
      "properties": {
        "script": {
          "type": "string",
          "description": "The script to execute"
        },
        "path": {
          "type": "string",
          "description": "The path to the package.json file. If omitted the package.json in the root of the workspace folder is used."
        }
      }
    }
  ]
}

任务定义使用 JSON 架构语法定义 required 和 properties 属性。type 属性定义任务类型。如果上面的示例：

"type": "npm" 将任务定义与 npm 任务关联起来
"required": [ "script" ] 将 script 属性定义为强制性的。path 属性是可选的。
"properties" : { ... } 定义了附加属性及其类型。

当扩展实际创建任务时，它需要传递一个符合 package.json 文件中贡献的任务定义的 TaskDefinition。对于 npm 示例，为 package.json 文件内的测试脚本创建任务如下所示：

let task = new vscode.Task({ type: 'npm', script: 'test' }, ....);

contributes.terminal

向 VS Code 贡献终端配置文件，允许扩展处理配置文件的创建。定义后，在创建终端配置文件时，该配置文件应出现。

{
  "activationEvents": ["onTerminalProfile:my-ext.terminal-profile"],
  "contributes": {
    "terminal": {
      "profiles": [
        {
          "title": "Profile from extension",
          "id": "my-ext.terminal-profile"
        }
      ]
    }
  }
}

定义后，该配置文件将出现在终端配置文件选择器中。激活时，通过返回终端选项来处理配置文件的创建：

vscode.window.registerTerminalProfileProvider('my-ext.terminal-profile', {
  provideTerminalProfile(
    token: vscode.CancellationToken
  ): vscode.ProviderResult<vscode.TerminalOptions | vscode.ExtensionTerminalOptions> {
    return { name: 'Profile from extension', shellPath: 'bash' };
  }
});

contributes.themes

向 VS Code 贡献颜色主题，定义工作台颜色和编辑器中语法标记的样式。

您必须指定一个标签、主题是深色主题还是浅色主题（以便其余的 VS Code 更改以匹配您的主题），以及文件的路径（JSON 格式）。

主题示例

{
  "contributes": {
    "themes": [
      {
        "label": "Monokai",
        "uiTheme": "vs-dark",
        "path": "./themes/monokai-color-theme.json"
      }
    ]
  }
}

color theme extension point example

请参阅颜色主题指南，了解如何创建颜色主题。

contributes.typescriptServerPlugins

贡献 TypeScript 服务器插件，以增强 VS Code 对 JavaScript 和 TypeScript 的支持。

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin"
      }
    ]
  }
}

上述示例扩展贡献了 typescript-styled-plugin，它为 JavaScript 和 TypeScript 增加了 styled-component 智能感知。此插件将从扩展加载，并且必须作为常规 NPM dependency 安装在扩展中。

{
  "dependencies": {
    "typescript-styled-plugin": "*"
  }
}

当用户使用 VS Code 的 TypeScript 版本时，TypeScript 服务器插件会为所有 JavaScript 和 TypeScript 文件加载。如果用户使用工作区版本的 TypeScript，它们不会被激活，除非插件显式设置 "enableForWorkspaceTypeScriptVersions": true。

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin",
        "enableForWorkspaceTypeScriptVersions": true
      }
    ]
  }
}

插件配置

扩展可以通过 VS Code 内置 TypeScript 扩展提供的 API 将配置数据发送到贡献的 TypeScript 插件。

// In your VS Code extension

export async function activate(context: vscode.ExtensionContext) {
  // Get the TS extension
  const tsExtension = vscode.extensions.getExtension('vscode.typescript-language-features');
  if (!tsExtension) {
    return;
  }

  await tsExtension.activate();

  // Get the API from the TS extension
  if (!tsExtension.exports || !tsExtension.exports.getAPI) {
    return;
  }

  const api = tsExtension.exports.getAPI(0);
  if (!api) {
    return;
  }

  // Configure the 'my-typescript-plugin-id' plugin
  api.configurePlugin('my-typescript-plugin-id', {
    someValue: process.env['SOME_VALUE']
  });
}

TypeScript 服务器插件通过 onConfigurationChanged 方法接收配置数据。

// In your TypeScript plugin

import * as ts_module from 'typescript/lib/tsserverlibrary';

export = function init({ typescript }: { typescript: typeof ts_module }) {
  return {
    create(info: ts.server.PluginCreateInfo) {
      // Create new language service
    },
    onConfigurationChanged(config: any) {
      // Receive configuration changes sent from VS Code
    }
  };
};

此 API 允许 VS Code 扩展将 VS Code 设置与 TypeScript 服务器插件同步，或动态更改插件的行为。看看 TypeScript TSLint 插件和 lit-html 扩展，了解该 API 在实践中是如何使用的。

contributes.views

向 VS Code 贡献一个视图。您必须指定视图的标识符和名称。您可以贡献到以下视图容器：

explorer：活动栏中的资源管理器视图容器
scm：活动栏中的源代码管理 (SCM) 视图容器
debug：活动栏中的运行和调试视图容器
test：活动栏中的测试视图容器
扩展贡献的自定义视图容器。

当用户打开该视图时，VS Code 将发出一个激活事件 onView:${viewId}（以下示例为 onView:nodeDependencies）。您还可以通过提供 when 上下文值来控制视图的可见性。当标题无法显示时（例如视图被拖到活动栏中时），将使用指定的 icon。当视图移出其默认视图容器并需要额外上下文时，将使用 contextualTitle。

{
  "contributes": {
    "views": {
      "explorer": [
        {
          "id": "nodeDependencies",
          "name": "Node Dependencies",
          "when": "workspaceHasPackageJSON",
          "icon": "media/dep.svg",
          "contextualTitle": "Package Explorer"
        }
      ]
    }
  }
}

views extension point example

视图的内容可以通过两种方式填充：

使用 TreeView，通过 createTreeView API 提供数据提供程序，或直接通过 registerTreeDataProvider API 注册数据提供程序来填充数据。树视图非常适合显示层级数据和列表。请参阅 tree-view-sample。
使用 WebviewView，通过 registerWebviewViewProvider 注册提供程序。Webview 视图允许在视图中渲染任意 HTML。有关更多详细信息，请参见 webview view 示例扩展。

contributes.viewsContainers

贡献一个视图容器，可以向其中贡献自定义视图。您必须指定视图容器的标识符、标题和图标。目前，您可以将它们贡献到活动栏 (activitybar) 和面板 (panel)。下面的示例展示了如何将 Package Explorer 视图容器贡献到活动栏，以及如何向其中贡献视图。

{
  "contributes": {
    "viewsContainers": {
      "activitybar": [
        {
          "id": "package-explorer",
          "title": "Package Explorer",
          "icon": "resources/package-explorer.svg"
        }
      ]
    },
    "views": {
      "package-explorer": [
        {
          "id": "package-dependencies",
          "name": "Dependencies"
        },
        {
          "id": "package-outline",
          "name": "Outline"
        }
      ]
    }
  }
}

Custom views container

图标规范

尺寸： 图标应为 24x24 并居中。
颜色： 图标应使用单一颜色。
格式： 建议图标使用 SVG 格式，但也接受任何图像文件类型。
状态： 所有图标继承以下状态样式：

状态不透明度

默认值 60%

Hover 100%

活动 100%

contributes.viewsWelcome

向自定义视图贡献欢迎内容。欢迎内容仅适用于空树视图。如果树没有子节点且没有 TreeView.message，则认为视图为空。按照惯例，任何单独占一行的命令链接都会显示为按钮。您可以使用 view 属性指定欢迎内容应应用的视图。欢迎内容的可见性可以通过 when 上下文值来控制。显示为欢迎内容的文本通过 contents 属性设置。

{
  "contributes": {
    "viewsWelcome": [
      {
        "view": "scm",
        "contents": "In order to use git features, you can open a folder containing a git repository or clone from a URL.\n[Open Folder](command:vscode.openFolder)\n[Clone Repository](command:git.clone)\nTo learn more about how to use git and source control in VS Code [read our docs](https://aka.ms/vscode-scm).",
        "when": "config.git.enabled && git.state == initialized && workbenchState == empty"
      }
    ]
  }
}

Welcome content example

可以为同一个视图贡献多个欢迎内容项。发生这种情况时，来自 VS Code 核心的内容优先，其次是来自内置扩展的内容，最后是来自所有其他扩展的内容。

contributes.walkthroughs

示例扩展

贡献演练（Walkthroughs）以显示在“入门”页面上。演练在安装您的扩展时会自动打开，并提供了一种向用户介绍您扩展功能的便捷方式。

演练由标题、描述、ID 和一系列步骤组成。此外，可以设置 when 条件来根据上下文键隐藏或显示演练。例如，解释 Linux 平台设置的演练可以给定 when: "isLinux"，使其仅出现在 Linux 机器上。

演练中的每个步骤都有标题、描述、ID 和媒体元素（图像或 Markdown 内容），以及一组可选的事件，这些事件将导致步骤被勾选（如下面的示例所示）。步骤描述是 Markdown 内容，支持 **粗体**、 __下划线__ 和 ``代码`` 渲染，以及链接。与演练类似，步骤可以被赋予 when 条件以根据上下文键隐藏或显示它们。

建议图像使用 SVG，因为它们具有缩放能力并支持 VS Code 的主题颜色。使用 Visual Studio Code Color Mapper Figma 插件可以轻松地在 SVG 中引用主题颜色。

{
  "contributes": {
    "walkthroughs": [
      {
        "id": "sample",
        "title": "Sample",
        "description": "A sample walkthrough",
        "steps": [
          {
            "id": "runcommand",
            "title": "Run Command",
            "description": "This step will run a command and check off once it has been run.\n[Run Command](command:getting-started-sample.runCommand)",
            "media": { "image": "media/image.png", "altText": "Empty image" },
            "completionEvents": ["onCommand:getting-started-sample.runCommand"]
          },
          {
            "id": "changesetting",
            "title": "Change Setting",
            "description": "This step will change a setting and check off when the setting has changed\n[Change Setting](command:getting-started-sample.changeSetting)",
            "media": { "markdown": "media/markdown.md" },
            "completionEvents": ["onSettingChanged:getting-started-sample.sampleSetting"]
          }
        ]
      }
    ]
  }
}

Walkthrough example

完成事件

默认情况下，如果没有提供 completionEvents 事件，当点击任何按钮时（如果步骤没有按钮，则在打开时），该步骤将被勾选。如果需要更精细的控制，可以提供 completionEvents 列表。

可用的完成事件包括：

onCommand:myCommand.id：当命令运行后勾选步骤。
onSettingChanged:mySetting.id：一旦给定设置被修改，即勾选步骤。
onContext:contextKeyExpression：当上下文键表达式评估为真时勾选步骤。
extensionInstalled:myExt.id：如果安装了给定扩展，则勾选步骤。
onView:myView.id：一旦给定视图变得可见，即勾选步骤。
onLink:https://...：一旦通过演练打开了给定链接，即勾选步骤。

一旦步骤被勾选，它将保持勾选状态，直到用户明确取消勾选步骤或重置其进度（通过入门：重置进度命令）。

5/28/2026

状态	不透明度
默认值	60%
Hover	100%
活动	100%

贡献点

contributes.authentication

contributes.breakpoints

contributes.chatInstructions

chatInstructions 属性

contributes.chatPromptFiles

chatPromptFiles 属性

contributes.chatSkills

chatSkills 属性

contributes.colors

contributes.commands

命令示例

命令图标规范

contributes.configuration

配置示例

配置架构

title

properties

设置标题

单类别和默认类别配置的显示标题

多类别配置的显示标题

配置属性架构

description / markdownDescription

type

order

enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels

deprecationMessage / markdownDeprecationMessage

其他 JSON Schema 属性

不支持的 JSON Schema 属性

scope

ignoreSync

链接到设置

contributes.configurationDefaults

contributes.customEditors

contributes.debuggers

调试器示例

contributes.grammars

语法示例

contributes.icons

contributes.iconThemes

文件图标主题示例

contributes.jsonValidation

contributes.keybindings

快捷键绑定示例

contributes.languages

语言示例

contributes.menus

菜单示例

命令面板菜单项的上下文特定可见性

组的排序

组内排序

contributes.problemMatchers

contributes.problemPatterns

contributes.productIconThemes

产品图标主题示例

contributes.resourceLabelFormatters

contributes.semanticTokenModifiers

contributes.semanticTokenScopes

contributes.semanticTokenTypes

contributes.snippets

contributes.submenus

子菜单示例

contributes.taskDefinitions

contributes.terminal

contributes.themes

主题示例

contributes.typescriptServerPlugins

插件配置

contributes.views

contributes.viewsContainers

图标规范

contributes.viewsWelcome

contributes.walkthroughs

完成事件