扩展点 - 《HBuilderX 插件开发指南》

configuration
- 属性列表
  - title
  - properties
- 示例
commands
- 示例
snippets
viewsContainers
views
- TreeView 示例
- WebView 示例
menus

扩展点是通过在插件package.json文件中contributes节点下定义的一些JSON格式的配置项。以下是目前HBuilderX支持的扩展点列表：

configuration

configuration扩展点，会将扩展的配置项注册到HBuilderX的全局可视化配置里设置-插件配置。

属性列表

title

每个插件扩展的配置是分配到同一组下的，title指的是该组的名称，一般写的是插件名称。

properties

properties内配置的是一个jsonobject对象，该对象的key代表着要扩展的配置项id，value是一个符合JSON Schema规范的jsonobject，目前支持的字段包括：

type 类型。支持的类型包括：string、boolean、number。
description 描述
default 默认值
enum 可选值，目前只有type为string或number时可用

示例

    "contributes": {
        "configuration":{
            "title":"eslint-js",
            "properties":{
                "eslint-js.autoFixOnSave":{
                    "type":"boolean",
                    "default":true,
                    "description":"保存时自动修复"
                },
                "eslint-js.validateOnDocumentChanged":{
                    "type":"boolean",
                    "default":false,
                    "description":"启用实时校验"
                }
            }
        }
    }

效果图如下：

commands

commands扩展点用于声明一个命令，命令可以通过menus扩展点和菜单关联到一起

注意：当一个命令将要执行时，将会触发一个onCommand:${commandId}的activationEvent用于激活监听该命令的插件

示例

    "contributes": {
        "commands": [
          {
            "command": "extension.firstExtension",
            "title": "Hello World"
          }
        ]
    }

snippets

snippets扩展点可以扩展指定编程语言的代码块，可扩展的编程语言Id列表见这里。扩展示例代码如下：

    "contributes": {
        "snippets": [
          {
            "language": "css",
            "path": "./snippets/css.json"
          },
          {
            "project":"uni-app",
            "language": "css",
            "path": "./snippets/condition_comment.json"
          }
        ]
    }

属性列表

属性名称	属性类型	是否必须	描述
project	String	否	是否只在指定的项目类型下生效，目前的可取值为”Web”,”App”,”Wap2App”,”uni-app”;如果要支持多项目类型可以通过逗号分隔，例如：”Web,uni-app,App”
language	String	是	编程语言ID，用于限定只在指定的语言下生效，语言Id的列表参见这里
path	String	是	要扩展的代码块列表文件路径，文件内容格式见下面

代码块格式

每个配置项的说明如下表：

名称	描述
`key`	代码块显示名称，显示在代码助手列表中的名字，以下例子中”console.log”就是一个key。
prefix	代码块的触发字符，就是敲什么字母匹配这个代码块。
body	代码块的内容。内容中有如下特殊格式： $1 表示代码块输入后光标的所在位置。如需要多光标，就在多个地方配置$1,如该位置有预置数据，则写法是${1:foo1}，多选项即下拉候选列表使用${1:foo1/foo2/foo3}； $2 表示代码块输入后再次按tab后光标的切换位置tabstops（代码块展开后按tab可以跳到下一个tabstop； $0 代表代码块输入后最终光标的所在位置（也可以按回车直接跳过去）。双引号使用\”转义，换行使用多个数组表示，每个行一个数组，用双引号包围，并用逗号分隔，缩进需要用\t表示，不能直接输入缩进！
triggerAssist	为true表示该代码块输入到文档后立即在第一个tabstop上触发代码提示，拉出代码助手，默认为false。

代码块示例

// ./snippets/javascript.json
{
    "console.log": {
        "prefix": "logtwo",
        "body": [
            "console.log('$1');",
            "\tconsole.log('${2:foo/bar}');"
        ],
        "triggerAssist": false,
        "description": "Log output to console twice"
    }
}

viewsContainers

在窗体左侧区域扩展一个和项目管理器同级的tab项，完整的扩展视图流程参考如何注册一个新的视图？

属性列表

属性名称	属性类型	是否必须	描述
activitybar	Array<ViewsContainerDef>	不是	定义扩展的视图容器列表，可在菜单`视图`-`显示扩展视图`中查看打开
rightside	Array<ViewsContainerDef>	不是	定义扩展的视图容器列表，可在菜单`视图`-`显示扩展视图`中查看打开

示例

   "contributes": {
       "viewsContainers": {
           "activitybar": [{
               "id": "demoview",
               "title": "DemoView"
           }],
           "rightside":[{
                   "id":"rightsideContainerId",
                   "title":"rightside Container Title"
          }]
       },
       "views": {
           "demoview": [{
               "id": "extensions.treedemo",
               "name": "DemoView"
           }]
       },
       ...
    }

ViewsContainerDef

属性名称	属性类型	是否必须	描述
id	String	是	扩展的视图容器(viewContainers)的id
title	String	是	显示在tab标签上的标题

views

扩展新的视图，扩展的view必须和viewsContainers内定义的视图容器绑定以后才能生效。目前支持TreeView和WebView，并且一个视图容器（viewsContainers）仅支持绑定一个视图（view）。在该扩展点声明后，需要通过API：window.createTreeView或者window.createWebView实现。完整的扩展视图流程参考如何注册一个新的视图？

TreeView 示例

    //NOTE：package.json不支持注释，以下代码使用时需要将注释删掉
   "contributes": {
       "views": {
           //绑定的视图容器（viewContainers）的Id，目前一个视图容器仅支持绑定一个视图（view）
           "demoview": [{
               //该id需要和window.createTreeView中的viewId参数一致
               "id": "extensions.treedemo",
               "name": "DemoView"
           }]
       }
    }

WebView 示例

从HBuilderX 2.8.1及以上版本开始支持

 "contributes": {
        "viewsContainers": {
            "rightside":[
                {
                    //该id需要和window.createWebView中的viewId参数一致
                    "id":"containerId",
                    "title":"Container Title"
                }
            ]
        },
        "views": {
            "containerId":[
                {
                    "id":"viewId",
                    "title":"Custom View Title"
                }
            ]
        },
        ...
     }

menus

menus扩展点会关联一个命令到相应的菜单项里面，当菜单触发时将会执行对应的命令。menus节点下配置的对象内的key指的是要注册到哪个弹出菜单里面，目前支持的key值列表如下：

editor/context ：编辑器右键菜单
explorer/context ：项目管理器右键菜单
view/item/context ：通过views扩展点扩展的视图的右键菜单（从HBuilderX 2.7.12及以上版本开始支持）
menubar/file : 顶部菜单的文件菜单
menubar/edit : 顶部菜单的编辑菜单
menubar/select : 顶部菜单的选择菜单
menubar/find : 顶部菜单的查找菜单
menubar/goto : 顶部菜单的跳转菜单
menubar/run : 顶部菜单的运行菜单
menubar/publish : 顶部菜单的发行菜单
menubar/view : 顶部菜单的视图菜单
menubar/tool : 顶部菜单的工具菜单
menubar/help : 顶部菜单的帮助菜单

属性列表

属性名称	属性类型	是否必须	描述
id	String	否	菜单项的Id，如何要配置二级菜单，则需要该属性
command	String	否	菜单项关联的`命令`Id
title	String	否	菜单项的名称，如果没有配置，将采用`命令`的title
group	String	是	菜单项要注册的位置,查看目前支持的group列表。注意该属性必须写，不写视为无效菜单扩展
when	String	否	控制菜单项是否显示的逻辑表达式,表达式说明
checked	String	否	`从HBuilderX 2.7.6及以上版本开始支持` 控制菜单项是否处于checked的逻辑表达式,表达式语法和when表达式一致

当属性title和command都为空时，将被识别为分割线。

示例

   "contributes": {
       "menus": {
         "editor/context": [
           {
             "id":"sep",
             "group": "z_commands"
           },
           {
             "command": "extension.firstExtension",
             "group": "z_commands",
             "when":"editorTextFocus"
           }
         ]
       }
    }

注册二级菜单

二级菜单通过将group设置为%menuId%@1、%menuId%@2的方式来实现，其中menuId指的是菜单扩展中的id字段。代码示例如下:

   "contributes": {
       "menus": {
         "editor/context": [
           {
             "id":"foo",
             "title": "带子菜单的菜单",
             "group": "z_commands",
           },
           {
             "command": "extension.firstExtension",
             "group": "foo@1",
             "when":"editorTextFocus"
           }
         ]
       }
    }

group

每个弹出菜单内的group都不一样，下面列出所有的弹出菜单下可用的group。

注意：想要将扩展菜单放到弹出菜单的最后，可以将group设置成0_foot

editor/context
- copy
- goto
- copyPath
- assist
- z_commands

对应的位置如下图所示：

explorer/context ：项目管理器右键菜单
- new
- openInExplorer
- nature
- cutcopy
- rename
- z_commands

对应的位置如下图所示：

menubar/file : 顶部菜单的文件菜单
- new
- tab
- save
- openInExplorer

对应的位置如下图所示：

menubar/edit : 顶部菜单的编辑菜单
- undo
- copy
- format
- line
- delete

对应的位置如下图所示：

menubar/select : 顶部菜单的选择菜单
- selectAll
- area
- word
- line
- colum
- 0_cursor
- 1_cursor

对应的位置如下图所示：

menubar/find : 顶部菜单的查找菜单
- findFile
- findWord
- findSymbol

对应的位置如下图所示：

menubar/goto : 顶部菜单的跳转菜单
- system_goto
- line_goto
- define_goto

对应的位置如下图所示：

menubar/run : 顶部菜单的运行菜单
- 0_foot

对应的位置在菜单的末尾。

menubar/publish : 顶部菜单的发行菜单
- 0_foot

对应的位置在菜单的末尾。

menubar/view : 顶部菜单的视图菜单
- min_window
- focus_editor
- show_lineno
- view_split
- scroll
- plus_font

对应的位置如下图所示：

menubar/tool : 顶部菜单的工具菜单
- shortcuts
- snippets
- ext_settings

对应的位置如下图所示：

menubar/help : 顶部菜单的帮助菜单
- documents
- checkupdate
- license

对应的位置如下图所示：

when

when表达式用来动态的判断某个条件是否满足(即表达式的运算结果是true或者false)，目前用于控制一个菜单是否显示。目前支持的表达式运算符如下：

操作符	描述	例子
`==`	相等	`langId == 'javascript'`
`!=`	不相等	`langId != 'html'`
`&&`	并且	`explorerResourceCount == 1 && explorerResourceIsFolder`
`\|\|`	或者	`explorerResourceIsFolder \|\| explorerResourceIsWorkspaceFolder`
`!`	非	`!explorerResourceIsFolder`

目前HBuilderX内置变量列表如下：

变量名	类型	描述
explorerResourceCount	Number	项目管理器选中的资源数量
explorerResourceIsFolder	Boolean	项目管理器选中的资源是否全是目录
explorerResourceIsWorkspaceFolder	Boolean	项目管理器选中的资源是否全是项目根目录
isSVN	Boolean	是否是SVN仓库下的文件
isGit	Boolean	是否是Git仓库下的文件
activeEditor.file.exists	Boolean	当前激活的编辑器打开的文件是否存在
activeEditor.file.isProjectFile	Boolean	当前激活的编辑器打开的文件是否是左侧项目管理器下的文件
activeEditor.readonly	Boolean	当前激活的编辑器是否是只读
editorTextFocus	Boolean	当前激活的编辑器是否有焦点
langId	String	当前激活的编辑器打开的文档的编程语言id，完整语言Id列表参见这里
viewItem	String	通过`views`扩展的视图中当前选择的item的contextValue
config.*	Any	获取某个配置项的值,例子： `config.editor.fontSize`