Contribution Point

VSCode开发

Contribution Points 是一组在 package.json 中 contributes 字段内的 JSON 声明。插件通过注册 Contribution Points 来扩展 vsCode 中的功能。

contributes.commands

commands 数组包含一组命令，用户可以通过命令面板(Ctrl+Shift+P)输入命令来触发，关键包括 command 和 title 两个：

{
    "contributes": [
        {
            "command": "anyField.commandName",
            "title": "commandTitleToShow",
            "category": "titlePrefixCategory"
        }
    ]
}

当一个命令触发时， VSCode 会 emit 一个 activationEvent onCommand:${command}。

contributes.viewsContainer

提供一个 view container 到 VSCode 活动区域（activityBar）或面板（panel）中。需要指定 view container 的 id、title、icon，id 对应一个 views。

"contributes": {
    "viewsContainers": {
        "activityBar": [
            "id": "custom-view",
            "title": "自定义插件",
            "icon": "resources/custom.svg"
        ]
    },
    "views": {
        "custom-view": [
            {
                "id": "welcome",
                "name": "Welcome"
            },
            {
                "id": "outline",
                "name": "Outline"
            }
        ]
    }
}

contributes.views

提供一个 view，必须指定 id、name，可以向以下 view containers 提供：

• explorer：Activity Bar 的资源管理器。
• scm：Activity Bar 的资源管理器（Source Control Management）view container。
• debug：在 Activity Bar 启动并调试 view container。
• test：在 Activity Bar 测试 view container。
• 插件提供的自定义 view containers

当一个 view 被打开时，VSCode 会 emit 一个 activationEvent onView:${viewId}。

可以通过提供 when 属性来控制 view 的可视性：

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

view 的内容有两种填充方式：

• 通过 TreeView 的 createTreeView API 提供一个 data provider，或者通过 registerTreeDataProvider API 直接注册一个 data provider 来填充数据。TreeView 是一种展示分层数据的理想方式。
• 通过 WebviewView 的 registerWebViewProvider 注册一个 provider。WebviewView 允许渲染任意的 HTML。

contributes.viewsWelcome

向自定义 views 提供 welcome 内容。只能作用于空的 treeViews（没有子节点）。任何单行的 command 链接，都会以按钮的形式展示。
view 属性声明了 welcome 内容展示的视图；when 属性可以控制可见性；contents 属性控制了展示的内容：

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

contributes.menus

向编辑器或导航条提供一个命令菜单。菜单项定义了选择时执行的 command 和展示条件 when。

在必须的 command 属性以外，一个可选的 command 可以通过 alt 属性定义，在打开菜单时按下 Alt 键即可展示。

group 属性定义了菜单项的分组。特殊的 navigation 分组永远展示在菜单的顶部起始位置。

通过 menu 执行一个命令时，VS Code 会尝试推断当前选中的菜单资源，并将其作为命令的参数。例如选中资源管理器的项目，会将所选资源的 URI 作为参数传递；编辑器菜单则会传递当前 document 的 URI。

支持展示菜单栏的位置

• commandPalette 全局命令栏
• explorer/context 资源管理器右键菜单
• editor/
  
  • context 编辑器右键菜单
  • title 编辑器标题菜单
  • title/context 编辑器标题右键菜单
• debug/
  
  • callstack/context debug调用栈右键菜单 & group inline debug调用栈的actions
  • variables/context debug变量区右键菜单
  • toolbar debug工具栏
• scm/
  
  • title
  • resourceGroup/context
  • resourceState/context
  • change/title
• view/
  
  • title
  • item/context
• touchbar macOS Touch Bar
• comments/
  
  • commentThread/title
  • commentThread/context
  • comment/title
  • comment/context
• timeline/
  
  • title
  • item/context
• extension/context 插件视图右键菜单

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

menus 的默认分组

编辑区右键

• navigation
• 1_modification
• 9_cutcopypaste
• z_commands

资源管理器右键

• navigation
• 2_workspace
• 3_compare
• 4_search
• 5_cutcopypaste
• 7_modification

编辑器tab右键

• 1_close
• 3_preview

编辑器标题菜单

• navigation
• 1_run
• 1_diff
• 3_open
• 5_close

插件视图右键菜单

• 1_copy
• 2_configure

Groups 内顺序

菜单栏分组内的顺序通过 @<number> 指定 order id 来实现：

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

contributes.configuration

confuguration keys 是暴露给用户设置的选项，用户可以在用户设置或者工作区设置里进行配置。

配置可以是一个单独的对象，表示一类配置项；也可以是多类配置项对象组成的数组。

多类配置项的情况下，设置面板里会通过插件子菜单表格的形式展示。

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

string 类型的 property 可以设置 "editPresentation": "multilineText" 来渲染一个多行文本输入框。

在插件中使用 vscode.workspace.getConfiguration('myExtension') 来获取配置。

properties 属性会成为配置项的字典，第一段是命名空间，第二段是小标题，再继续可以有其他配置段落，展示时不会展示第一段的内容；驼峰表示单词间隔，展示时会用空格分开。
例如 gitMagic.blame.dateFormat 和 gitMagic.blame.heatMap.enabled 会展示成：

Blame: Date Format
Blame > Heatmap: Enabled