快捷導(dǎo)航

VSCode插件開發(fā)全攻略之命令、菜單、快捷鍵

更新時間：2020年05月07日 14:51:14 作者：我是小茗同學(xué)

這篇文章主要介紹了VSCode插件開發(fā)全攻略之命令、菜單、快捷鍵,本文給大家介紹的非常詳細，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下

命令

我們在前面HelloWord章節(jié)中已經(jīng)提到了命令寫法，這里再重溫一下。

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

然后在清單文件聲明：

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

vscode.commands.registerCommand是注冊命令的API，執(zhí)行后會返回一個Disposable對象，所有注冊類的API執(zhí)行后都需要將返回結(jié)果放到context.subscriptions中去。

回調(diào)函數(shù)參數(shù)

回調(diào)函數(shù)接收一個可選參數(shù)uri：

當從資源管理器中右鍵執(zhí)行命令時會把當前選中資源路徑uri作為參數(shù)傳過；
當從編輯器中右鍵菜單執(zhí)行時則會將當前打開文件路徑URI傳過去；
當直接按Ctrl+Shift+P執(zhí)行命令時，這個參數(shù)為空；

示例：

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

最終效果：

編輯器命令

除了上面的注冊普通命令之外，還有一個vscode.commands.registerTextEditorCommand 命令，文本編輯器命令與普通命令不同，它們僅在有被編輯器被激活時調(diào)用才生效，此外，這個命令可以訪問到當前活動編輯器textEditor：

// 編輯器命令
context.subscriptions.push(vscode.commands.registerTextEditorCommand('extension.testEditorCommand', (textEditor, edit) => {
 console.log('您正在執(zhí)行編輯器命令！');
 console.log(textEditor, edit);
}));

執(zhí)行命令

這里先說一下vscode api的一個習(xí)慣設(shè)計，很多命令都是返回一個類似于Promise的Thenable對象，如果發(fā)現(xiàn)api里面返回的是這個對象，說明這個方法不是直接返回結(jié)果的。

使用代碼執(zhí)行某個命令：

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

獲取所有命令

前面說到了執(zhí)行命令，那我怎么知道某些操作它的命令是什么呢？

有2種方法，第一種通過代碼，getCommands接收一個參數(shù)表示是否過濾內(nèi)部命令，默認否：

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

一般有上千個命令：

另外一種方法是直接打開快捷鍵設(shè)置，這里就能看到所有命令列表，右鍵可以復(fù)制命令：

復(fù)雜命令

vscode內(nèi)部有一些復(fù)雜命令，所謂復(fù)雜命令，就是指一些需要特殊參數(shù)并且通常有返回值、執(zhí)行一些諸如跳轉(zhuǎn)到定義、執(zhí)行代碼高亮等特殊操作、這類命令有幾十個，作為插件開發(fā)者，很多時候你可能正需要這類命令，復(fù)雜命令列表參閱：https://code.visualstudio.com/docs/extensionAPI/vscode-api-commands

以下是演示如何在VS代碼中打開新文件夾的示例：

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

菜單

一個菜單項的完整配置如下：

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

editor/title是key值，定義這個菜單出現(xiàn)在哪里；when控制菜單合適出現(xiàn)；command定義菜單被點擊后要執(zhí)行什么操作；alt定義備用命令，按住alt鍵打開菜單時將執(zhí)行對應(yīng)命令；group定義菜單分組；

出現(xiàn)的位置

目前插件可以給以下場景配置自定義菜單：

資源管理器上下文菜單 - explorer/context

編輯器上下文菜單 - editor/context

編輯標題菜單欄 -editor/title

編輯器標題上下文菜單 -editor/title/context

調(diào)試callstack視圖上下文菜單 - debug/callstack/context

SCM標題菜單 -scm/title

SCM資源組菜單 -scm/resourceGroup/context

SCM資源菜單 -scm/resource/context

SCM更改標題菜單 -scm/change/title

左側(cè)視圖標題菜單 -view/title

視圖項菜單 -view/item/context

控制命令是否顯示在命令選項板中 - commandPalette

其中，最常見的應(yīng)該就explorer/context和editor/context了，這2個應(yīng)該不用多做介紹。

editor/title：

圖標在commands里面配置，light和dark分別對應(yīng)淺色和深色主題，如果不配置圖標則直接顯示文字：

"commands": [
 {
 "command": "extension.demo.testMenuShow",
 "title": "這個菜單僅在JS文件中出現(xiàn)",
 "icon": {
  "light": "./images/tool-light.svg",
  "dark": "./images/tool-light.svg"
 }
 }
]

editor/title/context：

when

通過可選的when語句，VS Code可以很好地控制什么時候顯示菜單項，當然，when語句語法不僅僅適用于菜單項的控制。

when語句語法有很多，這里列舉幾個常用的：

resourceLangId == javascript：當編輯的文件是js文件時；
resourceFilename == test.js：當當前打開文件名是test.js時；
isLinux 、isMac、isWindows：判斷當前操作系統(tǒng)；
editorFocus ：編輯器具有焦點時；
editorHasSelection ：編輯器中有文本被選中時；
view == someViewId：當當前視圖ID等于someViewId時；
等等等

多個條件可以通過與或非進行組合，例如：editorFocus && isWindows && resourceLangId == javascript。

有關(guān)when語句的更多完整語法請參考官方文檔：https://code.visualstudio.com/docs/getstarted/keybindings

alt

alt很好理解，表示沒有按下alt鍵時，點擊右鍵菜單執(zhí)行的是command對應(yīng)的命令，而按下了alt鍵后執(zhí)行的是alt對應(yīng)的命令。這里不做過多解釋。

group

組間排序

控制菜單的分組和排序。不同的菜單擁有不同的默認分組。

editor/context中有這些默認組：
navigation- 放在這個組的永遠排在最前面；
1_modification - 更改組；
9_cutcopypaste - 編輯組z_commands - 最后一個默認組，其中包含用于打開命令選項板的條目。

除了navigation是強制放在最前面之外，其它分組都是按照0-9、a-z的順序排列的，所以如果你想在1_modification和9_cutcopypaste插入一個新的組別的話，你可以定義一個諸如6_test：

explorer/context有這些默認組：

navigation - 放在這個組的永遠排在最前面；
2_workspace - 與工作空間操作相關(guān)的命令。
3_compare - 與差異編輯器中的文件比較相關(guān)的命令。
4_search - 與在搜索視圖中搜索相關(guān)的命令。
5_cutcopypaste - 與剪切，復(fù)制和粘貼文件相關(guān)的命令。
7_modification - 與修改文件相關(guān)的命令。

在編輯器選項卡上下文菜單有這些默認組：

1_close - 與關(guān)閉編輯器相關(guān)的命令。
3_preview - 與固定編輯器相關(guān)的命令。

在editor/title有這些默認組：

1_diff - 與使用差異編輯器相關(guān)的命令。
3_open - 與打開編輯器相關(guān)的命令。
5_close - 與關(guān)閉編輯器相關(guān)的命令。

組內(nèi)排序

默認同一個組的順序取決于菜單名稱，如果想自定義排序的話可以再組后面通過@<number>的方式來自定義順序，例如：

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

如上，默認情況下，按照菜單名排序，sayHello在getCurrentFilePath的前面，但是通過自定義順序，把后者放到了前面。

快捷鍵

快捷鍵設(shè)置的寫法比較簡單，如下所示：

"contributes": {
 "keybindings": [{
		// 指定快捷鍵執(zhí)行的操作
 "command": "extension.sayHello",
		// windows下快捷鍵
 "key": "ctrl+f10",
		// mac下快捷鍵
 "mac": "cmd+f10",
		// 快捷鍵何時生效
 "when": "editorTextFocus"
 }]
}

這個快捷鍵最終會出現(xiàn)在整個vscode快捷鍵設(shè)置界面：