命令

命令 (Commands) 可在 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);
  }
}

尋找可用命令

命令 URI

命令 URI 是用於執行特定命令的連結。它們可以作為可點擊的連結，用於懸停提示文字 (hover text)、完成項目詳細資料或 Webview 中。

命令 URI 使用 command 方案，後接命令名稱。例如，editor.action.addCommentLine 命令的命令 URI 是 command:editor.action.addCommentLine。以下是一個懸停提供者 (hover provider) 的範例，它會在作用中文字編輯器的目前行註解中顯示連結：

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 來啟用命令 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 繫結至處理函式。若要將此命令公開在「命令面板」(Command Palette) 中以便使用者發現，您還需要在擴充功能的 package.json 中設定對應的命令 contribution。

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

commands 貢獻點會告訴 VS Code 您的擴充功能提供了特定命令，並應在呼叫該命令時啟用，同時也讓您可以控制該命令在 UI 中的顯示方式。建立命令時，請務必遵循命令命名慣例。

The contributed command in the Command Palette

現在，當使用者第一次從命令面板或透過鍵盤快速鍵呼叫 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)

命令透過 enablement 屬性支援啟用狀態——其值為一個 when 子句。啟用狀態適用於所有選單以及已註冊的鍵盤快速鍵。

注意：enablement 與選單項目的 when 條件之間存在語意上的重疊。後者用於防止選單中充滿了已停用的項目。例如，分析 JavaScript 正規表示式的命令應該在檔案為 JavaScript 時顯示 (when)，並且僅在游標位於正規表示式上時才啟用 (enabled)。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);

命名慣例

建立命令時，您應遵循以下命名慣例：

命令標題
- 使用標題格式的大小寫 (Title-style capitalization)。不要大寫四個字母或更短的介係詞（例如 on、to、in、of、with 和 for），除非該介係詞是第一個或最後一個字。
- 以動詞開頭來描述將執行的動作。
- 使用名詞來描述動作的目標。
- 避免在標題中使用「command」一詞。

5/28/2026