命令

命令在 Visual Studio Code 中觸發操作。如果您曾經配置過鍵盤繫結，那麼您就已經使用過命令。擴充套件也使用命令來向用戶公開功能，繫結到 VS Code UI 中的操作，以及實現內部邏輯。

使用命令

VS Code 包含大量內建命令，您可以使用它們與編輯器互動、控制使用者介面或執行後臺操作。許多擴充套件還將其核心功能公開為命令，使用者和其他擴充套件都可以利用這些命令。

以程式設計方式執行命令

vscode.commands.executeCommand API 以程式設計方式執行命令。這讓您可以使用 VS Code 的內建功能，並基於 VS Code 的內建 Git 和 Markdown 擴充套件等擴充套件進行構建。

例如，editor.action.addCommentLine 命令註釋活動文字編輯器中當前選定的行

import * as vscode from 'vscode';

function commentLine() {
  vscode.commands.executeCommand('editor.action.addCommentLine');
}

某些命令採用控制其行為的引數。命令也可能返回結果。例如，類似 API 的 vscode.executeDefinitionProvider 命令查詢文件中給定位置的定義。它接受文件 URI 和位置作為引數，並返回一個包含定義列表的 Promise

import * as vscode from 'vscode';

async function printDefinitionsForActiveEditor() {
  const activeEditor = vscode.window.activeTextEditor;
  if (!activeEditor) {
    return;
  }

  const definitions = await vscode.commands.executeCommand<vscode.Location[]>(
    'vscode.executeDefinitionProvider',
    activeEditor.document.uri,
    activeEditor.selection.active
  );

  for (const definition of definitions) {
    console.log(definition);
  }
}

查詢可用命令

• 瀏覽鍵盤快捷鍵
• 檢視 VS Code 的內建高階命令 API

命令 URI

命令 URI 是執行給定命令的連結。它們可以用作懸停文字、完成項詳細資訊或 Webview 內可點選的連結。

命令 URI 使用 command 方案，後跟命令名稱。例如，editor.action.addCommentLine 命令的命令 URI 是 command:editor.action.addCommentLine。這是一個懸停提供程式，它在活動文字編輯器的當前行註釋中顯示一個連結

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  vscode.languages.registerHoverProvider(
    'javascript',
    new (class implements vscode.HoverProvider {
      provideHover(
        _document: vscode.TextDocument,
        _position: vscode.Position,
        _token: vscode.CancellationToken
      ): vscode.ProviderResult<vscode.Hover> {
        const commentCommandUri = vscode.Uri.parse(`command:editor.action.addCommentLine`);
        const contents = new vscode.MarkdownString(`[Add comment](${commentCommandUri})`);

        // To enable command URIs in Markdown content, you must set the `isTrusted` flag.
        // When creating trusted Markdown string, make sure to properly sanitize all the
        // input content so that only expected command URIs can be executed
        contents.isTrusted = true;

        return new vscode.Hover(contents);
      }
    })()
  );
}

命令的引數列表作為已正確 URI 編碼的 JSON 陣列傳遞：下面的示例使用 git.stage 命令建立懸停連結以暫存當前檔案

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  vscode.languages.registerHoverProvider(
    'javascript',
    new (class implements vscode.HoverProvider {
      provideHover(
        document: vscode.TextDocument,
        _position: vscode.Position,
        _token: vscode.CancellationToken
      ): vscode.ProviderResult<vscode.Hover> {
        const args = [{ resourceUri: document.uri }];
        const stageCommandUri = vscode.Uri.parse(
          `command:git.stage?${encodeURIComponent(JSON.stringify(args))}`
        );
        const contents = new vscode.MarkdownString(`[Stage file](${stageCommandUri})`);
        contents.isTrusted = true;
        return new vscode.Hover(contents);
      }
    })()
  );
}

您可以在建立 Webview 時，透過在 WebviewOptions 中設定 enableCommandUris，在Webview 中啟用命令 URI。

建立新命令

註冊命令

vscode.commands.registerCommand 將命令 ID 繫結到擴充套件中的處理函式

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const command = 'myExtension.sayHello';

  const commandHandler = (name: string = 'world') => {
    console.log(`Hello ${name}!!!`);
  };

  context.subscriptions.push(vscode.commands.registerCommand(command, commandHandler));
}

每當執行 myExtension.sayHello 命令時，無論是透過 executeCommand 以程式設計方式執行、透過 VS Code UI 還是透過鍵盤繫結，都會呼叫處理函式。

建立面向使用者的命令

vscode.commands.registerCommand 只將命令 ID 繫結到處理函式。要在命令面板中公開此命令，以便使用者可以發現它，您還需要在擴充套件的 package.json 中有一個相應的命令貢獻

{
  "contributes": {
    "commands": [
      {
        "command": "myExtension.sayHello",
        "title": "Say Hello"
      }
    ]
  }
}

commands 貢獻告訴 VS Code 您的擴充套件提供了給定命令，並且在呼叫該命令時應該啟用，它還允許您控制命令在 UI 中的顯示方式。建立命令時，請務必遵循命令命名約定。

現在，當用戶首次從命令面板或透過鍵盤繫結呼叫 myExtension.sayHello 命令時，擴充套件將被啟用，並且 registerCommand 將 myExtension.sayHello 繫結到適當的處理程式。

注意：針對 1.74.0 之前 VS Code 版本的擴充套件必須為所有面向用戶的命令顯式註冊一個 onCommand activationEvent，以便啟用擴充套件並執行 registerCommand

{
  "activationEvents": ["onCommand:myExtension.sayHello"]
}

內部命令不需要 onCommand 啟用事件，但您必須為以下任何命令定義它們

• 可以使用命令面板呼叫。
• 可以使用鍵盤繫結呼叫。
• 可以透過 VS Code UI（例如透過編輯器標題欄）呼叫。
• 旨在作為其他擴充套件使用的 API。

控制命令何時顯示在命令面板中

預設情況下，透過 package.json 的 commands 部分貢獻的所有面向用戶的命令都會顯示在命令面板中。但是，許多命令僅在某些情況下相關，例如當存在給定語言的活動文字編輯器時，或者當用戶設定了某個配置選項時。

menus.commandPalette 貢獻點允許您限制命令何時顯示在命令面板中。它採用目標命令的 ID 和一個控制命令何時顯示的when 子句

{
  "contributes": {
    "menus": {
      "commandPalette": [
        {
          "command": "myExtension.sayHello",
          "when": "editorLangId == markdown"
        }
      ]
    }
  }
}

現在，myExtension.sayHello 命令將僅在使用者位於 Markdown 檔案中時顯示在命令面板中。

命令的啟用

命令透過 enablement 屬性支援啟用——其值是一個when 子句。啟用適用於所有選單和已註冊的鍵盤繫結。

注意：enablement 和選單項的 when 條件之間存在語義重疊。後者用於防止選單中充滿停用項。例如，分析 JavaScript 正則表示式的命令應該在檔案是 JavaScript 時顯示，並且只有當游標位於正則表示式上方時才啟用。when 子句透過不為所有其他語言檔案顯示命令來防止混亂。強烈建議防止選單混亂。

最後，顯示命令的選單（如命令面板或上下文選單）實現不同的處理啟用方式。編輯器和資源管理器上下文選單呈現啟用/停用項，而命令面板則對其進行篩選。

使用自定義 when 子句上下文

如果您正在編寫自己的 VS Code 擴充套件，並且需要使用 when 子句上下文啟用/停用命令、選單或檢視，並且現有鍵都不適合您的需求，那麼您可以新增自己的上下文。

下面的第一個示例將鍵 myExtension.showMyCommand 設定為 true，您可以在命令的啟用或 when 屬性中使用它。第二個示例儲存了一個值，您可以在 when 子句中使用它來檢查開啟的酷東西的數量是否大於 2。

vscode.commands.executeCommand('setContext', 'myExtension.showMyCommand', true);

vscode.commands.executeCommand('setContext', 'myExtension.numberOfCoolOpenThings', 2);

命名約定

建立命令時，您應該遵循以下命名約定

• 命令標題
  • 使用標題樣式大寫。不要將少於四個字母的介詞（例如 on、to、in、of、with 和 for）大寫，除非介詞是第一個或最後一個單詞。
  • 以動詞開頭，描述將要執行的操作。
  • 使用名詞描述操作的目標。
  • 避免在標題中使用“命令”。