コマンド

コマンドは 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 は、指定されたコマンドを実行するリンクです。ホバーテキスト、補完アイテムの詳細、または 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 に対応するコマンド 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 が適切なハンドラーに紐付けられます。

注意: VS Code バージョン 1.74.0 より前のバージョンを対象とする拡張機能では、拡張機能がアクティブ化されて registerCommand が実行されるよう、ユーザー向けのすべてのコマンドに対して onCommand activationEvent を明示的に登録する必要があります。
{
  "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）」され、カーソルが正規表現の上にある場合にのみ「有効（enablement）」になるようにします。when 句を使用すれば、他の言語ファイルでコマンドを表示しないようにして、メニューの煩雑さを防ぐことができます。メニューをすっきりさせることは強く推奨されます。

最後に、コマンドパレットやコンテキストメニューのようなコマンドを表示するメニューは、有効化の処理に関してそれぞれ異なる方法を実装しています。エディタやエクスプローラーのコンテキストメニューは有効/無効の状態を描画しますが、コマンドパレットはそれらをフィルタリングします。

カスタム when 句コンテキストの使用

独自の VS Code 拡張機能を作成していて、when 句コンテキストを使用してコマンド、メニュー、またはビューを有効/無効にする必要があり、既存のキーでは要件を満たせない場合は、独自のコンテキストを追加できます。

以下の最初の例では myExtension.showMyCommand というキーを true に設定しており、これをコマンドの有効化や when プロパティで使用できます。2 番目の例では、値を変数に格納し、when 句で「クールな開いているアイテム」の数が 2 より多いかどうかをチェックする例です。

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

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

命名規則

コマンドを作成する際は、以下の命名規則に従う必要があります。

コマンドタイトル
- タイトル形式の大文字小文字を使用してください。前置詞（on, to, in, of, with, for など）が最初または最後の単語でない限り、4文字以下の前置詞は小文字のままにしてください。
- 実行されるアクションを説明するために、動詞で始めてください。
- アクションの対象を説明するために、名詞を使用してください。
- タイトルに "command" という単語を使用することは避けてください。

4/8/2026