VScode 插件中package.json 文件中 Contribution 字段配置详解

Contributes Points

contributes points 是在 package.json 中的一组 JSON 声明

• configuration：设置
• configurationDefaults
• commands：命令
• menus：菜单
• keybindings：快捷键绑定
• languages：语言支持
• debuggers：调试
• breakpoints：断点
• grammars：
• themes：主题
• iconThemes：图标主题
• productIconThemes：
• snippets：代码片段
• jsonValidation：自定义 JSON 校验
• views：左侧侧边栏视图
• viewsWelcome：
• viewsContainers：自定义 activitybar
• walkthroughs
• problemMatchers
• problemPatterns
• taskDefinitions
• colors
• typescriptServerPlugins
• resourceLabelFormatters
• customEditors

1、configuration

配置

{
  "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."
        }
      }
    }
  }
}

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

1. title

标题

标题应该是您的插件的确切名称。

• ✅ "title": "GitMagic"
• ❌ "title": "GitMagic Extension"
• ❌ "title": "GitMagic Configuration"
• ❌ "title": "GitMagic Extension Configuration Settings"

2. properties

属性

配置的 key 将用于命名空间和构造标题。key 的大写字母用于表示分词。

例如，如果您的 key 是 gitMagic.blame.dateFormat，则为该设置生成的标题将如下所示：

Blame: Date Format

会将根据 key 中建立层次结构进行分组。

例如：

gitMagic.blame.dateFormat
gitMagic.blame.format
gitMagic.blame.heatMap.enabled
gitMagic.blame.heatMap.location

将会出现在一个组中，如：

Blame: Date Format
Blame: Format
Blame › Heatmap: Enabled
Blame › Heatmap: Location

否则，属性按照字母顺序出现

1. description / markdownDescription

描述

描述出现在标题之后和输入字段之前，布尔值除外，其中描述用作复选框的标签。

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

如果您使用 markdownDescription 而不是 description，您的设置描述将在 settings 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://momentjs.com/docs/#/displaying/format/) for valid formats"
  }
}

2. type

类型：[number, string, boolean, object, array, ...]

number、string、boolean 可以直接在 settings UI 中编辑，boolean 将会作为复选框的标签

{
  "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"
  }
}

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

object、array 等不能在 settings UI 中展示，只能在 JSON 进行修改。

3. enum / enumDescriptions / markdownEnumDescriptions

enum：枚举：如果提供一个数组，则会展示下拉选项 enumDescriptions：枚举描述 markdownEnumDescriptions：将呈现为 markdown 模式。

{
  "gitMagic.blame.heatmap.location": {
    "type": "string",
    "default": "right",
    "enum": ["left", "right"],
    "enumDescriptions": [
      "Adds a heatmap indicator on the left edge of the gutter blame annotations",
      "Adds a heatmap indicator on the right edge of the gutter blame annotations"
    ]
  }
}

4. deprecationMessage / markdownDeprecationMessage

{
  "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."
  }
}

5. default

定义属性的默认值

6. minimum / maximum

限制数值的最大值和最小值

7. maxLength / minLength

限制字符串长度

8. pattern

使用正则限制字符串

9. format

限制字符串的格式：date、time、ipv4、email、uri

10. maxItems / minItems

限制数组长度

11. scope

范围

属性值：

• application：适用于所有 VScode 实例的设置，只能在用户设置中设置
• machine：在用户或远程设置中设置的机器特定设置
• machine-overridable：可以被工作区或者文件夹设置的机器特定设置
• window：可以在用户、工作区或远程设置中配置的 windows 特定设置
• resource：适用于文件和文件夹的资源设置，可以在所有设置级别进行设置，甚至文件夹设置
• language-overridable：可以在语言级别覆盖的资源设置

如果未声明范围，则默认为窗口。

12. Linking to settings

指向另一个设置的链接

在 markdown 类型属性中使用以下特殊语法：#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`.",
    // ...
}

在 settings UI 界面展示为：

2、configurationDefaults

默认配置

{
  "contributes": {
    "configurationDefaults": {
      "[markdown]": {
        "editor.wordWrap": "on",
        "editor.quickSuggestions": false
      }
    }
  }
}

3、commands

命令

由 title、icon（可选）、category、command 命令组成。默认情况下，命令显示在命令面板 (⇧⌘P) 中，但它们也可以显示在其他菜单中。

当调用命令时，VS Code 将发出 activationEvent onCommand:${command}

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

command icon 的规格

• 尺寸：图标应为 16x16，内边距为 1 像素（图像为 14x14）并居中。
• 颜色：图标应使用单一颜色。
• 格式：建议图标为 SVG，但可以接受任何图像文件类型。

4、menus

菜单项

1. 可以选择的拓展项

• 全局命令面板 - commandPalette
• 资源管理器上下文菜单 - explorer/context
• 编辑器上下文菜单 - editor/context
• 编辑器标题菜单栏 - editor/title
• 编辑器标题上下文菜单 - editor/title/context
• 调试调用堆栈视图上下文菜单 - debug/callstack/context
• 调试调用堆栈视图内联操作 - debug/callstack/context group inline
• 调试变量视图上下文菜单 - debug/variables/context
• 调试工具栏 - debug/toolbar
• SCM 标题菜单 - scm/title
• SCM 资源组菜单 - scm/resourceGroup/context
• SCM 资源文件夹菜单 - scm/resourceFolder/context
• SCM 资源菜单 - scm/resourceState/context
• SCM 更改标题菜单 - scm/change/title
• SCM 源代码控制菜单 - scm/sourceControl
• 视图标题菜单 - view/title
• 查看项目菜单 - view/item/context
• macOS 触控栏 - touchBar
• 注释线程标题菜单栏 - comments/commentThread/title
• 注释线程上下文菜单 - comments/commentThread/context
• 注释标题菜单栏 - comments/comment/title
• 注释上下文菜单 - comments/comment/context
• 时间线视图标题菜单栏 - timeline/title
• 时间线视图项目上下文菜单 - timeline/item/context
• 扩展视图上下文菜单 - extension/context

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

2. 可以通过 when 来控制何时可见

"menus": {
    "commandPalette": [
      {
        "command": "extension.sayHello",
        "when": "editorHasSelection"
      }
    ]
}

仅当被选中时可见

3. 分组排序

1. editor context menu 默认组

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

2. explorer context menu 默认组

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

3. editor tab context menu 默认组

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

4. editor title menu 默认组

• navigation：与导航相关的命令
• 1_run：与运行和调试编辑器相关的命令
• 1_diff：与使用差异编辑器相关的命令
• 3_open：与打开编辑器相关的命令
• 5_close：与关闭编辑器相关的命令

5. Timeline view item context menu 默认组

• inline：重要或常用的时间线项目命令
• 1_actions：与使用时间线项目相关的命令
• 5_copy：与复制时间线项目相关的命令

6. Extensions view context menu 默认组

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

4. 在组内排序

通过 @<number> 附加到组内来指定的

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

5、keybindings

快捷键绑定

当 win/linux 触发 Ctrl+F1 或者 MacOS 触发 Cmd + F1 时，调用 extension.sayHello 命令

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

6、languages

语言

作用：

• 定义一个可以在 VS Code API 的其他部分重用的 languageId
• 将文件扩展名、文件名模式、以特定行开头的文件、mimetypes 与该语言 ID 相关联。

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

7、debuggers

调试器

• type 是用于在启动配置中标识此调试器的唯一 ID
• label 是此调试器在 UI 中的用户可见名称
• program 编写调试适配器的路径，该适配器针对实际调试器或运行时实现 VS Code 调试协议
• runtime 如果调试适配器的路径不是可执行文件但需要运行时
• configurationAttributes 是特定于此调试器的启动配置参数的架构。 请注意，不支持 JSON 架构构造 $ref 和定义
• 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"
        }
      }
    ]
  }
}

8、breakpoints

断点

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

9、grammars

为一种语言写一个 TextMate 语法，包含语法的文件可以是 JSON 或者 XML plist 格式

必须指定一个 label

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

10、themes

主题

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

11、iconThemes

图标主题

必须指定一个 id，一个 label 和一个 path

{
  "contributes": {
    "iconThemes": [
      {
        "id": "metro",
        "label": "Metro File Icons",
        "path": "./fileicons/metro-file-icon-theme.json"
      }
    ]
  }
}

12、productIconThemes

产品图标主题

必须指定一个 id，一个 label 和一个 path

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

13、snippets

代码片段

为 go 语言添加一份代码片段

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

14、jsonValidation

JSON 验证

为特定的 JSON 文件提供验证, url 可以时本地文件也可以时网络文件

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

15、views

视图

必须为视图指定标识符和名称

• explorer: 活动栏中的资源管理器视图容器
• scm: 活动栏中的源代码管理 (SCM) 视图容器
• debug: 在活动栏中运行和调试视图容器
• test: 活动栏中的测试视图容器
• Custom view：扩展提供的自定义视图容器

当用户打开视图时，VScode 将会发出一个 activationEvent onView:${viewId}

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

两种方式填充视图内容

1. 通过 createTreeView API 提供数据提供者或直接通过 registerTreeDataProvider API 注册数据提供者来填充数据，从而使用 TreeView
2. 通过使用 registerWebviewViewProvider 注册提供程序来使用 WebviewView, Webview 视图允许在视图中呈现任意 HTML。

16、viewsWelcome

欢迎视图，仅适用于空树视图

{
  "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"
      }
    ]
  }
}

17、viewsContainers

视图容器，必须为视图容器指定 identifier (标识符)、title (标题)、和 icon

{
  "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"
        }
      ]
    }
  }
}

图标规则

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

State	Opacity
Default	60%
Hover	100%
Active	100%

18、walkthroughs

演示，在开始页面提供演示，由标题、描述、ID 和一系列步骤组成

演示中每个步骤都有一个标题、描述、ID 和媒体元素(图像或者 markdown 内容)，以及一系列将导致检查步骤的可选择事件

{
  "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"]
          }
        ]
      }
    ]
  }
}

1. Completion events

默认情况下，如果没有提供 completion events 事件，单击任何按钮时将关闭该步骤，或者如果该步骤没有按钮，则在打开时将其选中，可以提供一个 completionEvents 列表

可用的 Completion Events 事件：

• onCommand:myCommand.id：在命令运行时
• onSettingChanged:mySetting.id：一旦给定设置被修改
• onContext:contextKeyExpression：当上下文键表达式计算为真时
• extensionInstalled:myExt.id：如果安装了给定的扩展
• onView:myView.id：一旦给定的视图变得可见
• onLink:https://...：一旦通过演示打开给定链接。

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

19、problemMatchers

问题匹配

{
  "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
        }
      }
    ]
  }
}

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

可以通过名称引用 $gcc 在 tasks.json 文件中使用此问题匹配器

20、problemPatterns

问题模式

21、taskDefinitions

任务定义，至少要有一个类型属性，通常需要定义附加属性

{
  "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": "npm" 将任务定义与 npm 任务相关联
• "required": [ "script" ] 将该脚本属性定义为必需的。 path 属性是可选的
• "properties" : { ... } 定义附加属性及其类型

当创建一个任务时，需要传递一个符合 package.json 文件中贡献的任务定义 TaskDefinition

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

22、colors

主题颜色，定义后，用户可以在 workspace.colorCustomization 设置中自定义颜色，用户主题可以设置颜色值。

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

插件可以使用 ThemeColor API 使用新的和现有的主题颜色

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

23、typescriptServerPlugins

提供 TypeScript 服务器插件，以增强 VS Code 的 JavaScript 和 TypeScript 支持

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

上面的示例扩展提供了 typescript-styled-plugin，它为 JavaScript 和 TypeScript 添加了样式组件 IntelliSense

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

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

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

24、resourceLabelFormatters

提供资源标签格式化程序，指定如何在工作台中的任何地方显示 URI

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

25、customEditors

customEditors 是你的差距如何告诉 VS Code 它提供的自定义编辑器

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

customEditors 是一个数组，所以插件可以贡献多个自定义编辑器

• viewType - 自定义编辑器的唯一标识符 这就是 VS Code 如何将 package.json 中的自定义编辑器贡献与代码中的自定义编辑器实现联系起来。这在所有扩展中必须是唯一的，因此不要使用通用的 viewType，例如 “preview”，请确保使用对您的扩展而言唯一的视图类型，例如 “viewType”：“myAmazingExtension.svgPreview”
• displayName - 在 VS Code 的 UI 中标识自定义编辑器的名称 display name 是在 VScode UI 中向用户显示的
• selector - 指定自定义编辑器对哪些文件处于活动状态 selector (选择器)是一个或多个 glob 模式的数组。这些 glob 模式与文件名匹配，以确定是否可以对它们使用自定义编辑器。诸如 *.png 之类的 filenamePattern 将为所有 PNG 文件启用自定义编辑器
• priority - 优先级（可选）指定何时使用自定义编辑器 当资源打开时使用自定义编辑器的优先级控制。可能的值为：
  • default
  • option