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 句はコンテキストキー (たとえば 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:\/\// ですが、JSON 文字列ではバックスラッシュをエスケープする必要があり、正規表現パターンではスラッシュをエスケープする必要があるため、when 句では /file:\\/\\// になります。
• !=~ 演算子はありませんが、マッチ式を否定できます - !(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 句をサポートするよりリッチな条件付きおよび動的な貢献が可能になります。

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

以下に、ブール値の true/false に評価される利用可能なコンテキストキーの一部を示します。

ここに記載されているリストはすべてを網羅しているわけではありません。その他の when 句コンテキストは、キーボード ショートカット エディター (ユーザー設定: キーボード ショートカットを開く) で検索およびフィルタリングするか、既定のキーバインディング JSON ファイル (ユーザー設定: 既定のキーボード ショートカット (JSON) を開く) を確認することで見つけることができます。また、コンテキストキーの検査ユーティリティを使用して、関心のあるコンテキストキーを特定することもできます。

注: ここでは、プレフィックス "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 番目の例では、when 句を使用して、開いているクールなものの数が 2 より大きいかどうかを確認できる値を保存しています。

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

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

コンテキストキーの検査ユーティリティ

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

開発者: コンテキストキーを検査を実行すると、カーソルが VS Code UI の要素をハイライト表示し、要素をクリックすると、現在のコンテキストキーとその状態がオブジェクトとしてコンソールに出力されます。

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

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