菜单

package.json

一个菜单项的完整配置如下:

"contributes": {
    "menus": {
        "editor/title": [{
            "when": "resourceLangId == markdown",
            "command": "markdown.showPreview",
            "alt": "markdown.showPreviewToSide",
            "group": "navigation"
        }]
    }
}
  • editor/title 是key值,定义这个菜单出现在哪里;
  • when 控制菜单何时出现;
  • command 定义菜单被点击后要执行什么操作;
  • alt 定义备用命令,按住alt键打开菜单时将执行对应命令;
  • group 定义菜单分组;

设定菜单出现的位置

目前插件可以给以下场景配置自定义菜单:

  1. 资源管理器上下文菜单 - explorer/context
  2. 编辑器上下文菜单 - editor/context
  3. 编辑标题菜单栏 - editor/title
  4. 编辑器标题上下文菜单 - editor/title/context
  5. 调试callstack视图上下文菜单 - debug/callstack/context
  6. SCM标题菜单 - scm/title
  7. SCM资源组菜单 - scm/resourceGroup/context
  8. SCM资源菜单 - scm/resource/context
  9. SCM更改标题菜单 - scm/change/title
  10. 左侧视图标题菜单 - view/title
  11. 视图项菜单 - view/item/context
  12. 控制命令是否显示在命令选项板中 - commandPalette

其中,最常见的应该就explorer/contexteditor/context

图标

图标在commands里面配置,lightdark分别对应浅色和深色主题,如果不配置图标则直接显示文字:

"commands": [
    {
        "command": "extension.demo.testMenuShow",
        "title": "这个菜单仅在JS文件中出现",
        "icon": {
            "light": "./images/tool-light.svg",
            "dark": "./images/tool-light.svg"
        }
    }
]

when

通过可选的when语句,VS Code可以很好地控制什么时候显示菜单项,当然,when语句语法不仅仅适用于菜单项的控制。

when语句语法有很多,这里列举几个常用的:

选项 释义
resourceLangId == javascript 当编辑的文件是js文件时;
resourceFilename == test.js 当当前打开文件名是test.js时;
isLinux、isMac、isWindows 判断当前操作系统;
editorFocus 编辑器具有焦点时;
editorHasSelection 编辑器中有文本被选中时;
view == someViewId 当当前视图ID等于someViewId时;

等等等

多个条件可以通过与或非进行组合

例如:editorFocus && isWindows && resourceLangId == javascript

有关when语句的更多完整语法请参考官方文档

alt

alt很好理解,表示没有按下alt键时,点击右键菜单执行的是command对应的命令,而按下了alt键后执行的是alt对应的命令。这里不做过多解释。

group

组间排序

控制菜单的分组和排序

不同的菜单拥有不同的默认分组。

editor/context中有这些默认组:

  • navigation - 放在这个组的永远排在最前面;
  • 1_modification - 更改组;
  • 9_cutcopypaste - 编辑组
  • z_commands - 最后一个默认组,其中包含用于打开命令选项板的条目。

除了navigation是强制放在最前面之外,其它分组都是按照0-9a-z的顺序排列的

所以如果想在1_modification9_cutcopypaste插入一个新的组别的话,可以定义一个诸如6_test

explorer/context有这些默认组:

  • navigation - 放在这个组的永远排在最前面;
  • 2_workspace - 与工作空间操作相关的命令。
  • 3_compare - 与差异编辑器中的文件比较相关的命令。
  • 4_search - 与在搜索视图中搜索相关的命令。
  • 5_cutcopypaste - 与剪切,复制和粘贴文件相关的命令。
  • 7_modification - 与修改文件相关的命令。

在编辑器选项卡上下文菜单有这些默认组:

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

editor/title有这些默认组:

1_diff - 与使用差异编辑器相关的命令。 3_open - 与打开编辑器相关的命令。 5_close - 与关闭编辑器相关的命令。

组内排序

默认同一个组的顺序取决于菜单名称,如果想自定义排序的话可以在组后面通过@<number>的方式来自定义顺序,例如:

"editor/context": [
    {
        "when": "editorFocus",
        "command": "extension.sayHello",
        // 强制放在navigation组的第2个
        "group": "navigation@2"
    },
    {
        "when": "editorFocus",
        "command": "extension.demo.getCurrentFilePath",
        // 强制放在navigation组的第1个
        "group": "navigation@1"
    }
]

如上,默认情况下,按照菜单名排序,sayHellogetCurrentFilePath的前面,但是通过自定义顺序,把后者放到了前面。