贡献点

贡献点是您在package.json 扩展清单的contributes 字段中进行的一组 JSON 声明。您的扩展注册贡献点以扩展 Visual Studio Code 中的各种功能。以下是所有可用贡献点的列表。

contributes.breakpoints

通常，调试器扩展还将具有contributes.breakpoints 条目，其中扩展列出了将启用设置断点的语言文件类型。

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

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": "TypeScript",
      "properties": {
        "typescript.useCodeSnippetsOnMethodSuggest": {
          "type": "boolean",
          "default": false,
          "description": "Complete functions with their parameter signature."
        },
        "typescript.tsdk": {
          "type": ["string", "null"],
          "default": null,
          "description": "Specifies the folder path containing the tsserver and lib*.d.ts files to use."
        }
      }
    }
  }
}

configuration extension point example

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

配置模式

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

settings UI screenshot with numbers

标题

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

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

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

对于title 和displayName 字段，诸如“扩展”、“配置”和“设置”之类的词语是多余的。

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

属性

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

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

设置标题

在设置 UI 中，将使用多个字段来构造每个设置的显示标题。键中的大写字母用于指示单词断点。

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

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

例如，对于设置 IDgitMagic.blame.dateFormat 和扩展名称authorName.gitMagic，由于设置 ID 的前缀与扩展名称的后缀匹配，因此在显示标题中将删除设置 ID 的gitMagic 部分：“Blame：日期格式”。

多类别配置的显示标题

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

例如，对于设置 IDcss.completion.completePropertyWithSemicolon 和类别 IDcss，由于设置 ID 的前缀与类别 ID 的后缀匹配，因此在设置 UI 中将删除设置 ID 的css 部分，并且生成的设置标题将为“Completion：使用分号完成属性”。

配置属性模式

配置键使用 JSON 模式的超集定义。

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`。

类型

类型为 `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`（如果没有指定 `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` 属性值，或者同一个类别中的两个设置具有相同的 `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` 将在设置 UI 中作为 Markdown 渲染。

示例

{
  "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 参考。

范围

一个配置设置可以具有以下可能的范围之一

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 窗口或工作区（这可能是多根目录的）。

链接到设置

你可以在 markdown 类型的属性中使用以下特殊语法，插入指向另一个设置的链接，该链接将在设置 UI 中渲染为可点击的链接：`#target.setting.id#`。这将在 `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`，例如 `"preview"`，确保使用一个对你的扩展是唯一的 `viewType`，例如 `"viewType": "myAmazingExtension.svgPreview"`。
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 贡献一个新图标，以及一个默认图标。然后，扩展（或任何依赖于扩展的其他扩展）可以在可以使用 ThemeIcon 的任何地方使用该图标 ID 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 的主要影响是

定义一个 languageId，可以在 VS Code API 的其他部分重复使用，例如 vscode.TextDocument.languageId 和 onLanguage 激活事件。
- 您可以使用 aliases 字段贡献一个人类可读的标签。列表中的第一项将用作人类可读的标签。
将文件名扩展名 (extensions)、文件名 (filenames)、文件名 glob 模式 (filenamePatterns)、以特定行开头的文件（例如哈希邦）(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/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 - 与使用 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" : { ... } 定义附加属性及其类型。

当扩展实际创建一个任务时，它需要传递一个 TaskDefinition，该定义符合在 package.json 文件中贡献的任务定义。对于 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 IntelliSense。此插件将从扩展加载，并且必须作为扩展中的正常 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 直接注册数据提供者来填充数据。TreeView 非常适合显示层次数据和列表。请参阅 tree-view-sample。
使用 WebviewView，通过使用 registerWebviewViewProvider 注册提供者。Webview 视图允许在视图中呈现任意 HTML。有关更多详细信息，请参阅 webview 视图示例扩展。

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%

悬停 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

示例扩展

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

演练包括标题、说明、ID 和一系列步骤。此外，可以设置 when 条件，以便根据上下文键隐藏或显示演练。例如，解释在 Linux 平台上进行设置的演练可以被赋予 when: "isLinux"，以便仅在 Linux 机器上显示。

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

建议使用 SVG 作为图像，因为它们具有可缩放性，并且支持 VS Code 的主题颜色。使用 Visual Studio Code 颜色映射器 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://...：通过演练打开给定链接后选中步骤。

选中步骤后，该步骤将保持选中状态，直到用户显式取消选中步骤或重置其进度（通过“入门：重置进度”命令）。

10/29/2024

状态	不透明度
默认	60%
悬停	100%
活动	100%

贡献点

contributes.breakpoints

contributes.colors

contributes.commands

命令示例

命令图标规范

contributes.configuration

配置示例

配置模式

标题

属性

设置标题

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

多类别配置的显示标题

配置属性模式

description / markdownDescription

类型

顺序

enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels

deprecationMessage / markdownDeprecationMessage

其他 JSON Schema 属性

不支持的 JSON Schema 属性

范围

链接到设置

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

完成事件