🚀 VS Code で で入手しましょう！

コマンド

コマンドは 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 contribution は、拡張機能が特定のコマンドを提供し、そのコマンドが呼び出されたときにアクティブ化する必要があることを VS Code に伝え、コマンドが UI にどのように表示されるかを制御することもできます。コマンドを作成するときは、コマンドの命名規則に従ってください。

The contributed command in the Command Palette

ユーザーがコマンドパレットまたはキーバインドから myExtension.sayHello コマンドを最初に呼び出すと、拡張機能がアクティブ化され、registerCommand が myExtension.sayHello を適切なハンドラーにバインドします。

注: VS Code バージョン 1.74.0 より前のバージョンを対象とする拡張機能は、すべてのユーザー向けコマンドに対して onCommand activationEvent を明示的に登録して、拡張機能がアクティブ化され、registerCommand が実行されるようにする必要があります。

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

内部コマンドには onCommand アクティベーションイベントは必要ありませんが、次のコマンドには定義する必要があります。

  • コマンドパレットを使用して呼び出すことができる。
  • キーバインドを使用して呼び出すことができる。
  • エディターのタイトルバーなど、VS Code UI を介して呼び出すことができる。
  • 他の拡張機能が利用するための API として意図されている。

コマンドパレットにコマンドが表示されるタイミングの制御

デフォルトでは、package.json の commands セクションを通じて提供されるすべてのユーザー向けコマンドは、コマンドパレットに表示されます。ただし、多くのコマンドは、特定の状況でのみ関連性があります。たとえば、特定の言語のアクティブなテキストエディターがある場合や、ユーザーが特定の構成オプションを設定している場合などです。

menus.commandPalette contribution point を使用すると、コマンドをコマンドパレットに表示するタイミングを制限できます。ターゲットコマンドの ID と、コマンドが表示されるタイミングを制御する when 句 を受け取ります。

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

これで、ユーザーが Markdown ファイルにいる場合のみ、myExtension.sayHello コマンドがコマンドパレットに表示されるようになります。

コマンドの有効化

コマンドは、enablement プロパティを介して有効化をサポートしています。その値は when 句 です。有効化は、すべてのメニューと登録済みのキーバインドに適用されます。

注: enablement とメニュー項目の when 条件の間には、意味的な重複があります。後者は、無効な項目でいっぱいのメニューを防ぐために使用されます。たとえば、JavaScript 正規表現を分析するコマンドは、ファイルが JavaScript の場合に表示され、カーソルが正規表現の上にある場合のみ有効にする必要があります。when 句は、他のすべての言語ファイルに対してコマンドを表示しないことで、混乱を防ぎます。メニューの混乱を防ぐことを強くお勧めします。

最後に、コマンドパレットやコンテキストメニューなど、コマンドを表示するメニューは、有効化の処理方法が異なります。エディターとエクスプローラーのコンテキストメニューは、有効/無効項目をレンダリングしますが、コマンドパレットはそれらをフィルター処理します。

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

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

以下の最初の例では、キー myExtension.showMyCommand を true に設定します。これは、コマンドの有効化または when プロパティで使用できます。2 番目の例では、クールなオープンなものの数が 2 より大きいかどうかを when 句で確認するために使用できる値を格納します。

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

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

命名規則

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

  • コマンドタイトル
    • タイトルスタイルの大文字表記を使用します。前置詞が最初または最後の単語でない限り、4 文字以下の前置詞（on、to、in、of、with、for など）を大文字にしないでください。
    • 実行されるアクションを説明する動詞で始めます。
    • アクションのターゲットを説明する名詞を使用します。
    • タイトルに「command」を使用しないでください。
04/03/2025