VSCode插件开发笔记 3

前言

笔者正在学习开发一款VSCode插件，文章为学习所做的笔记，供学习使用。

1. 命令的写法

在 extension.js中可以定义想要执行的命令。
以下为直观阅读，将代码合成了一句展示。

function activate(context) {
  context.subscriptions.push(vscode.commands.registerCommand('extension.sayHello', () => {
    vscode.window.showInformationMessage('您执行了extension.sayHello命令！');
  }));
}

注册命令的API：vscode.commands.registerCommand ，
执行后返回一个 Disposable 对象。
所有注册类的 API 执行后都需要将返回结果放到 context.subscriptions中。

在清单文件声明注册的命令

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

1.1 回调函数的可选参数

回调函数接收一个可选参数 uri：

当从资源管理器中右键执行命令时会把当前选中资源路径 uri 作为参数传过；
当从编辑器中右键菜单执行时则会将当前打开文件路径 URI 传过去；
当直接按 Ctrl+Shift+P 执行命令时，这个参数为空；

示例：

context.subscriptions.push(vscode.commands.registerCommand('extension.demo.getCurrentFilePath', (uri) => {
    vscode.window.showInformationMessage(`当前文件(夹)路径是：${uri ? uri.path : '空'}`);
}));

package.json 如下：

    "menus": {
            "editor/context": [
                {
                    "when": "editorFocus",
                    "command": "extension.demo.getCurrentFilePath",
                    "group": "navigation"
                }
            ],
            "explorer/context": [
                {
                    "command": "extension.demo.getCurrentFilePath",
                    "group": "navigation"
                }
            ]
        }
    }

1.2 编辑器命令

注册普通命令的API：vscode.commands.registerCommand ，
注册文本编辑器命令：vscode.commands.registerTextEditorCommand，仅在编辑器被激活时调用才生效，此外，这个命令可以访问到当前活动编辑器 textEditor

// 编辑器命令
context.subscriptions.push(vscode.commands.registerTextEditorCommand('extension.testEditorCommand', (textEditor, edit) => {
    console.log('您正在执行编辑器命令！');
    console.log(textEditor, edit);
}));

1.3 获取所有的命令

// 获取所有命令
vscode.commands.getCommands().then(allCommands => {
    console.log('所有命令：', allCommands);
});

getCommands 接收一个参数表示是否过滤内部命令，默认否。
另外一种方法是直接打开快捷键设置，就能看到所有命令列表。

1.4 执行命令和复杂的命令

VSCode api的一个习惯设计：很多命令都是返回一个类似于 Promise 的Thenable 对象。

使用代码执行某个命令：

vscode.commands.executeCommand('命令', 'params1', 'params2', ...).then(result => {
    console.log('命令结果', result);
});

复杂命令，就是指一些需要特殊参数并且通常有返回值、执行一些诸如跳转到定义、执行代码高亮等特殊操作、这类命令有几十个。复杂命令列表参阅

示例：在VS代码中打开新文件夹

let uri = Uri.file('/some/path/to/folder');
commands.executeCommand('vscode.openFolder', uri).then(sucess => {
    console.log(success);
});

2. 菜单

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

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

editor/title 是 key 值，定义这个菜单出现在哪里；
when 控制菜单什么时候出现；
command 定义菜单被点击后要执行什么操作；
alt 定义备用命令，按住alt键打开菜单时将执行对应命令；
group定义菜单分组；

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

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

2.1 关于when

通过可选的when语句，VS Code可以很好地控制什么时候显示菜单项。

resourceLangId == javascript：当编辑的文件是js文件时；
resourceFilename == test.js：当当前打开文件名是test.js时；
isLinux、isMac、isWindows：判断当前操作系统；
editorFocus：编辑器具有焦点时；
editorHasSelection：编辑器中有文本被选中时；
view == someViewId：当当前视图ID等于 someViewId 时；
等等等
多个条件可以通过与或非进行组合。有关when语句的更多完整语法请参考官方文档

2.2 关于alt

没有按下 alt 键时，点击右键菜单执行的是 command 对应的命令，而按下了 alt 键后执行的是 alt 对应的命令。

2.3 关于group

组间排序

控制菜单的分组和排序。不同的菜单拥有不同的默认分组。

editor/context 的默认组：

navigation 放在这个组的永远排在最前面；
1_modification 更改组；
9_cutcopypaste 编辑组
z_commands 最后一个默认组，其中包含用于打开命令选项板的条目。
navigation是强制放在最前面，其它分组都是按照0-9、a-z的顺序排列的。

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

3. 快捷键

设置快捷键：

"contributes": {
    "keybindings": [{
        // 指定快捷键执行的操作
        "command": "extension.sayHello",
        // windows下快捷键
        "key": "ctrl+f10",
        // mac下快捷键
        "mac": "cmd+f10",
        // 快捷键何时生效
        "when": "editorTextFocus"
    }]
}

参考

VSCode插件开发全攻略（四）命令、菜单、快捷键