when 句のコンテキスト

Visual Studio Code は、VS Code UI 上でどの要素が表示され、アクティブになっているかに応じて、さまざまなコンテキストキーと特定の値を設定します。これらのコンテキストは、拡張機能のコマンドや、メニューやビューなどの UI 要素を条件付きで有効または無効にするために使用できます。

例えば、VS Code は when 句を使用してコマンドのキーバインドを有効または無効にします。これは「デフォルトのキーバインド JSON」（基本設定: デフォルトのキーボードショートカット (JSON) を開く）で確認できます。

{ "key": "f5",  "command": "workbench.action.debug.start",
                   "when": "debuggersAvailable && !inDebugMode" },

上記のように、組み込みのデバッグの開始コマンドには F5 というキーボードショートカットが割り当てられており、これは適切なデバッガーが利用可能であり（コンテキストキー debuggersAvailable が true）、かつエディターがデバッグモードではない（コンテキストキー inDebugMode が false）場合にのみ有効になります。

条件演算子

when 句は、1つのコンテキストキー（例: inDebugMode）で構成することも、さまざまな演算子を使用してより詳細なエディターの状態を表現することもできます。

論理演算子

論理演算子を使用すると、単純なコンテキストキーや、他の論理演算子、等価演算子、比較演算子、マッチ演算子、in/not in 演算子、または括弧で囲まれた式を含む when 句の式を組み合わせることができます。

論理演算子の優先順位に関する注意: 上表は、優先順位が高いものから低いものの順に並んでいます。例

等価演算子

コンテキストキーの値が指定された値と等しいかどうかを確認できます。右辺は値であり、コンテキストキーとして解釈されない（つまり、コンテキスト内で検索されない）ことに注意してください。

注記

• 右辺の値が空白を含む文字列の場合は、シングルクォートで囲む必要があります - "resourceFilename == 'My New File.md'"。
• === は == と同じ動作をし、!== は != と同じ動作をします。

比較演算子

コンテキストキーの値を数値と比較できます。演算子の左辺と右辺は空白で区切る必要があることに注意してください（foo < 1 は正しいが、foo<1 は不可）。

マッチ演算子

(旧名称: キー値ペアマッチ演算子)

when 句にはマッチ演算子 (=~) があります。式 key =~ regularExpressionLiteral は、右辺を正規表現リテラルとして扱い、左辺と照合します。例えば、すべての Docker ファイルに対してコンテキストメニュー項目を提供する場合、以下のように使用できます。

   "when": "resourceFilename =~ /docker/"

注記

• =~ 演算子の右辺は、JavaScript の正規表現リテラル（リファレンス）と同じルールに従いますが、JSON 文字列と正規表現の両方のエスケープルールに従う必要があります。例えば、サブ文字列 file:// に一致させるための正規表現リテラルは、JavaScript では /file:\/\// ですが、when 句では /file:\\/\\// となります。これは、JSON 文字列内でバックスラッシュをエスケープし、正規表現パターン内でスラッシュをエスケープする必要があるためです。
• !=~ 演算子は存在しませんが、マッチ式を否定することで同様のことが可能です - !(foo =~ /baz/)。

正規表現フラグ

正規表現リテラルでフラグを使用できます。例えば、resourceFilename =~ /json/i や myContextKey =~ /baz/si などです。

サポートされているフラグ: i, s, m, u。

無視されるフラグ: g, y。

'in' および 'not in' 条件演算子

when 句の in 演算子を使用すると、別のコンテキストキーの値内でコンテキストキーの値を動的に検索できます。例えば、特定の種類のファイルを含むフォルダー（または静的に判定できないもの）にコンテキストメニューコマンドを追加したい場合、in 演算子を使用して実現できます。反対の条件を確認するには not in 演算子を使用します。

まず、どのフォルダーでコマンドをサポートするかを決定し、フォルダー名を配列に追加します。次に、setContext コマンドを使用して、その配列をコンテキストキーにします。

vscode.commands.executeCommand('setContext', 'ext.supportedFolders', [
  'test',
  'foo',
  'bar'
]);

// or

// Note in this case (using an object), the value doesn't matter, it is based on the existence of the key in the object
// The value must be of a simple type
vscode.commands.executeCommand('setContext', 'ext.supportedFolders', {
  test: true,
  foo: 'anything',
  bar: false
});

次に、package.json に explorer/context メニューの貢献を追加できます。

// Note, this assumes you have already defined a command called ext.doSpecial
"menus": {
  "explorer/context": [
    {
      "command": "ext.doSpecial",
      "when": "explorerResourceIsFolder && resourceFilename in ext.supportedFolders"
    }
  ]
}

この例では、resourceFilename の値（この場合はフォルダー名）を取得し、ext.supportedFolders の値の中に存在するかどうかを確認しています。存在すればメニューが表示されます。この強力な演算子により、メニューやビューなど、when 句をサポートする、よりリッチで動的な貢献が可能になります。

利用可能なコンテキストキー

以下は、Boolean の true/false に評価される利用可能なコンテキストキーの一部です。

このリストはすべてではありません。他の when 句のコンテキストは、キーボードショートカットエディター（基本設定: キーボードショートカットを開く）で検索・フィルターするか、デフォルトのキーバインド JSON ファイル（基本設定: デフォルトのキーボードショートカット (JSON) を開く）を確認することで見つけることができます。また、Inspect Context Keys ユーティリティを使用して、興味のあるコンテキストキーを特定することもできます。

注意: ブール値に評価されるすべてのユーザー設定またはワークスペース設定は、"config." プレフィックスを付けることでここで使用できます。

表示/フォーカスされたビューの when 句コンテキスト

特定のビューが表示されているか、フォーカスされているかを確認する when 句を作成できます。

ビューの識別子

• workbench.explorer.fileView - ファイルエクスプローラー
• workbench.explorer.openEditorsView - 開いているエディター
• outline - アウトラインビュー
• timeline - タイムラインビュー
• workbench.scm - ソース管理
• workbench.scm.repositories - ソース管理リポジトリ
• workbench.debug.variablesView - 変数
• workbench.debug.watchExpressionsView - ウォッチ
• workbench.debug.callStackView - コールスタック
• workbench.debug.loadedScriptsView - ロードされたスクリプト
• workbench.debug.breakPointsView - ブレークポイント
• workbench.debug.disassemblyView - 逆アセンブリ
• workbench.views.extensions.installed - インストール済みの拡張機能
• extensions.recommendedList - 推奨される拡張機能
• workbench.panel.markers.view - 問題
• workbench.panel.output - 出力
• workbench.panel.repl.view - デバッグコンソール
• terminal - 統合ターミナル
• workbench.panel.comments - コメント

表示されているビューコンテナーの when 句コンテキスト

特定のビューコンテナーが表示されているかを確認する when 句を作成できます。

ビューコンテナーの識別子

• workbench.view.explorer - ファイルエクスプローラー
• workbench.view.search - 検索
• workbench.view.scm - ソース管理
• workbench.view.debug - 実行
• workbench.view.extensions - 拡張機能
• workbench.panel.markers - 問題
• workbench.panel.output - 出力
• workbench.panel.repl - デバッグコンソール
• terminal - 統合ターミナル
• workbench.panel.comments - コメント

特定のビューコンテナーにフォーカスがある場合にのみ有効な when 句を作成したい場合は、sideBarFocus, panelFocus, auxiliaryBarFocus を activeViewlet, activePanel, activeAuxiliary コンテキストキーと組み合わせて使用します。

例えば、以下の when 句は、ファイルエクスプローラーにフォーカスがある場合にのみ true となります。

"sideBarFocus && activeViewlet == 'workbench.view.explorer'"

when 句での設定の確認

when 句では、config. をプレフィックスとして付けることで、構成（設定）値を参照できます（例: config.editor.tabCompletion や config.breadcrumbs.enabled）。

カスタム when 句コンテキストの追加

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

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

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

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

Inspect Context Keys ユーティリティ

現在アクティブなすべてのコンテキストキーを実行時に確認したい場合は、コマンドパレットから Developer: Inspect Context Keys コマンドを使用できます（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。Inspect Context Keys は、コンテキストキーとその値を VS Code 開発者ツールのコンソール (Console) タブ（ヘルプ > 開発者ツールの切り替え）に表示します。

Developer: Inspect Context Keys を実行すると、カーソルで VS Code UI の要素を強調表示できます。要素をクリックすると、現在のコンテキストキーとその状態がオブジェクトとしてコンソールに出力されます。

アクティブなコンテキストキーのリストは非常に広範囲であり、インストールしている拡張機能からのカスタムコンテキストキーが含まれる場合があります。

注意: 一部のコンテキストキーは VS Code 内部用であり、将来変更される可能性があります。