命令

我們在前面HelloWord章節中已經提到了命令寫法，這裡再重溫一下。

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

然後在清單檔案宣告：

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

vscode.commands.registerCommand是註冊命令的API，執行後會返回一個Disposable物件，所有註冊類的API執行後都需要將返回結果放到context.subscriptions中去。

回撥函式引數

回撥函式接收一個可選引數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"
                }
            ]
        }
    }
 

最終效果：

編輯器命令

除了上面的註冊普通命令之外，還有一個vscode.commands.registerTextEditorCommand命令，文字編輯器命令與普通命令不同，它們僅在有被編輯器被啟用時呼叫才生效，此外，這個命令可以訪問到當前活動編輯器textEditor：

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

執行命令

這裡先說一下vscode api的一個習慣設計，很多命令都是返回一個類似於Promise的Thenable物件，如果發現api裡面返回的是這個物件，說明這個方法不是直接返回結果的。

使用程式碼執行某個命令：

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

獲取所有命令

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

有2種方法，第一種通過程式碼，getCommands接收一個引數表示是否過濾內部命令，預設否：

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

一般有上千個命令：

另外一種方法是直接開啟快捷鍵設定，這裡就能看到所有命令列表，右鍵可以複製命令：

複雜命令

vscode內部有一些複雜命令，所謂複雜命令，就是指一些需要特殊引數並且通常有返回值、執行一些諸如跳轉到定義、執行程式碼高亮等特殊操作、這類命令有幾十個，作為外掛開發者，很多時候你可能正需要這類命令，複雜命令列表參閱：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值，定義這個選單出現在哪裡；
• when控制選單合適出現；
• command定義選單被點選後要執行什麼操作；
• alt定義備用命令，按住alt鍵開啟選單時將執行對應命令；
• group定義選單分組；

出現的位置

目前外掛可以給以下場景配置自定義選單：

• 資源管理器上下文選單 - explorer/context
• 編輯器上下文選單 - editor/context
• 編輯標題選單欄 - editor/title
• 編輯器標題上下文選單 - editor/title/context
• 除錯callstack檢視上下文選單 - debug/callstack/context
• SCM標題選單 -scm/title
• SCM資源組選單 -scm/resourceGroup/context
• SCM資源選單 -scm/resource/context
• SCM更改標題選單 -scm/change/title
• 左側檢視標題選單 -view/title
• 檢視項選單 -view/item/context
• 控制命令是否顯示在命令選項板中 - commandPalette

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

editor/title：

圖示在commands裡面配置，light和dark分別對應淺色和深色主題，如果不配置圖示則直接顯示文字：

"commands": [
    {
        "command": "extension.demo.testMenuShow",
        "title": "這個選單僅在JS檔案中出現",
        "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：判斷當前作業系統；
• editorFocus：編輯器具有焦點時；
• editorHasSelection：編輯器中有文字被選中時；
• view == someViewId：噹噹前檢視ID等於someViewId時；
• 等等等

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

有關when語句的更多完整語法請參考官方文件：https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts

alt

alt很好理解，表示沒有按下alt鍵時，點選右鍵選單執行的是command對應的命令，而按下了alt鍵後執行的是alt對應的命令。這裡不做過多解釋。

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 - 與工作空間操作相關的命令。
• 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": "[email protected]"
    },
    {
        "when": "editorFocus",
        "command": "extension.demo.getCurrentFilePath",
        // 強制放在navigation組的第1個
        "group": "[email protected]"
    }
]

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

快捷鍵

快捷鍵設定的寫法比較簡單，如下所示：

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

這個快捷鍵最終會出現在整個vscode快捷鍵設定介面：

如果您想了解更多有關快捷鍵繫結的詳細細節可以繼續閱讀官方文件：https://code.visualstudio.com/docs/getstarted/keybindings