VS Codeのエージェントモードを拡張するには、を試してください！

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 句式を組み合わせることができます。

演算子 記号 例
Not ! "!editorReadonly" または "!(editorReadonly || inDebugMode)"
And && "textInputFocus && !editorReadonly"
Or || "isLinux || isWindows"

論理演算子の優先順位に関する注記: 上記の表は、優先順位が高いものから低いものの順に演算子をリストしています。例

記述 解釈
!foo && bar (!foo) && bar
!foo || bar (!foo) || bar
foo || bar && baz foo || (bar && baz)
!foo && bar || baz (!foo && bar) || baz
!(foo || bar) && baz (同じまま) !(foo || bar) && baz

等値演算子

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

演算子 記号 例
等値 == "editorLangId == typescript" または "editorLangId == 'typescript'"
不等値 != "resourceExtname != .js" または "resourceExtname != '.js'"

注

  • 右辺の値が空白文字を含む文字列の場合、単一引用符で囲む必要があります - "resourceFilename == 'My New File.md'"。
  • === は == と同じ動作をし、!== は != と同じ動作をします。

比較演算子

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

演算子 シンボル 例
より大きい >, >= "gitOpenRepositoryCount >= 1" は可能ですが、"gitOpenRepositoryCount>=1" は不可能です。
より小さい <, <= "workspaceFolderCount < 2" は可能ですが、"workspaceFolderCount<2" は不可能です。

マッチ演算子

(以前の名前: キーと値のペアのマッチ演算子)

演算子 記号 例
マッチ =~ "resourceScheme =~ /^untitled$|^file$/"

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

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

注

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

正規表現フラグ

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

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

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

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

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

演算子 記号 例
In in "resourceFilename in supportedFolders"
Not in not in "resourceFilename not in supportedFolders"

まず、コマンドをサポートするフォルダーを決定し、フォルダー名を配列に追加します。次に、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)) を確認することで見つけることができます。また、コンテキストキーの検査ユーティリティを使用して、関心のあるコンテキストキーを特定することもできます。

コンテキスト名 真の条件
エディターコンテキスト
editorFocus エディター (テキストまたはウィジェット) がフォーカスされている。
editorTextFocus エディターのテキストがフォーカスされている (カーソルが点滅している)。
textInputFocus 任意のエディターがフォーカスされている (通常のエディター、デバッグ REPL など)。
inputFocus 任意のテキスト入力領域がフォーカスされている (エディターまたはテキストボックス)。
editorTabMovesFocus Tab キーがエディターからフォーカスを移動するかどうか。
editorHasSelection エディターでテキストが選択されている。
editorHasMultipleSelections 複数のテキスト領域が選択されている (複数カーソル)。
editorReadonly エディターは読み取り専用である。
editorLangId エディターに関連付けられた言語 ID が一致する場合に True。
例: "editorLangId == typescript"。
isInDiffEditor アクティブなエディターが差分エディターである。
isInEmbeddedEditor フォーカスが埋め込みエディター内にある場合に True。
オペレーティングシステムコンテキスト
isLinux OS が Linux の場合に True。
isMac OS が macOS の場合に True。
isWindows OS が Windows の場合に True。
isWeb Web からエディターにアクセスしている場合に True。
リストコンテキスト
listFocus リストがフォーカスされている。
listSupportsMultiselect リストが複数選択をサポートしている。
listHasSelectionOrFocus リストが選択またはフォーカスされている。
listDoubleSelection リストに2つの要素が選択されている。
listMultiSelection リストに複数の要素が選択されている。
モードコンテキスト
inSnippetMode エディターがスニペットモードである。
inQuickOpen Quick Open ドロップダウンがフォーカスされている。
リソースコンテキスト
resourceScheme リソース URI スキームが一致する場合に True。
例: "resourceScheme == file"
resourceFilename エクスプローラーまたはエディターのファイル名が一致する場合に True。
例: "resourceFilename == gulpfile.js"
resourceExtname エクスプローラーまたはエディターのファイル名拡張子が一致する場合に True。
例: "resourceExtname == .js"
resourceDirname エクスプローラーまたはエディターのリソース絶対フォルダーパスが一致する場合に True。
例: "resourceDirname == /users/alice/project/src"
resourcePath エクスプローラーまたはエディターのリソース絶対パスが一致する場合に True。
例: "resourcePath == /users/alice/project/gulpfile.js"
resourceLangId エクスプローラーまたはエディターのタイトル言語 ID が一致する場合に True。
例: "resourceLangId == markdown"
isFileSystemResource エクスプローラーまたはエディターのファイルが、ファイルシステムプロバイダーから処理できるファイルシステムリソースである場合に True。
resourceSet エクスプローラーまたはエディターファイルが設定されている場合に True。
resource エクスプローラーまたはエディターファイルの完全な URI。
エクスプローラーコンテキスト
explorerViewletVisible エクスプローラービューが表示されている場合に True。
explorerViewletFocus エクスプローラービューがキーボードフォーカスを持っている場合に True。
filesExplorerFocus ファイルエクスプローラーセクションがキーボードフォーカスを持っている場合に True。
openEditorsFocus 開いているエディターセクションがキーボードフォーカスを持っている場合に True。
explorerResourceIsFolder エクスプローラーでフォルダーが選択されている場合に True。
エディターウィジェットコンテキスト
findWidgetVisible エディター検索ウィジェットが表示されている。
suggestWidgetVisible 候補ウィジェット (IntelliSense) が表示されている。
suggestWidgetMultipleSuggestions 複数の候補が表示されている。
renameInputVisible 名前変更入力テキストボックスが表示されている。
referenceSearchVisible Peek References ピークウィンドウが開いている。
inReferenceSearchEditor Peek References ピークウィンドウのエディターがフォーカスされている。
config.editor.stablePeek ピークエディターを開いたままにする (editor.stablePeek 設定で制御)。
codeActionMenuVisible コードアクションメニューが表示されている。
parameterHintsVisible パラメーターヒントが表示されている (editor.parameterHints.enabled 設定で制御)。
parameterHintsMultipleSignatures 複数のパラメーターヒントが表示されている。
デバッガーコンテキスト
debuggersAvailable 適切なデバッガー拡張機能が利用可能である。
inDebugMode デバッグセッションが実行中である。
debugState アクティブなデバッガーの状態。
可能な値は inactive、initializing、stopped、running。
debugType デバッグタイプが一致する場合に True。
例: "debugType == 'node'"。
inDebugRepl デバッグコンソール REPL にフォーカスがある。
統合ターミナルコンテキスト
terminalFocus 統合ターミナルがフォーカスされている。
terminalIsOpen 統合ターミナルが開いている。
タイムラインビューコンテキスト
timelineFollowActiveEditor タイムラインビューがアクティブエディターを追跡している場合に True。
タイムラインビューアイテムコンテキスト
timelineItem タイムラインアイテムのコンテキスト値が一致する場合に True。
例: "timelineItem =~ /git:file:commit\\b/"。
拡張機能コンテキスト
extension 拡張機能の ID が一致する場合に True。
例: "extension == eamodio.gitlens"。
extensionStatus 拡張機能がインストールされている場合に True。
例: "extensionStatus == installed"。
extensionHasConfiguration 拡張機能に構成がある場合に True。
グローバル UI コンテキスト
notificationFocus 通知がキーボードフォーカスを持っている。
notificationCenterVisible 通知センターが VS Code の右下で表示されている。
notificationToastsVisible 通知トーストが VS Code の右下で表示されている。
searchViewletVisible 検索ビューが開いている。
sideBarVisible サイドバーが表示されている。
sideBarFocus サイドバーがフォーカスされている。
panelFocus パネルがフォーカスされている。
inZenMode ウィンドウが Zen モードである。
isCenteredLayout エディターが中央レイアウトモードである。
workbenchState empty、folder (1つのフォルダー)、または workspace のいずれか。
workspaceFolderCount ワークスペースフォルダーの数。
replaceActive 検索ビューの置換テキストボックスが開いている。
view view/title および view/item/context の場合、コマンドを表示するビュー。
例: "view == myViewsExplorerID"。
viewItem view/item/context の場合、ツリーアイテムからの contextValue。
例: "viewItem == someContextValue"。
webviewId webview/context の場合、コマンドを表示する webview ID。
例: "webviewId == catCoding"。
isFullscreen ウィンドウがフルスクリーンである場合に True。
focusedView 現在フォーカスされているビューの識別子。
canNavigateBack 元に戻るナビゲーションが可能である場合に True。
canNavigateForward 次に進むナビゲーションが可能である場合に True。
canNavigateToLastEditLocation 最後に編集した場所にナビゲーションが可能である場合に True。
グローバルエディター UI コンテキスト
textCompareEditorVisible 少なくとも1つの差分 (比較) エディターが表示されている。
textCompareEditorActive 差分 (比較) エディターがアクティブである。
editorIsOpen 1つのエディターが開いている場合に True。
groupEditorsCount グループ内のエディターの数。
activeEditorGroupEmpty アクティブなエディターグループにエディターがない場合に True。
activeEditorGroupIndex エディターグリッド内のエディターグループの位置を反映する 1 から始まる数値。
インデックス 1 のグループは左上隅の最初のグループになります。
activeEditorGroupLast エディターグリッド内の最後のエディターグループの場合に true になります。
multipleEditorGroups 複数のエディターグループが存在する場合に True。
activeEditor グループ内のアクティブなエディターの識別子。
activeEditorIsDirty グループ内のアクティブなエディターがダーティである場合に True。
activeEditorIsNotPreview グループ内のアクティブなエディターがプレビューモードではない場合に True。
activeEditorIsPinned グループ内のアクティブなエディターがピン留めされている場合に True。
inSearchEditor 検索エディター内にフォーカスがある場合に True。
activeWebviewPanelId 現在アクティブな webview パネルの ID。
activeCustomEditorId 現在アクティブなカスタムエディターの ID。
構成設定コンテキスト
config.editor.minimap.enabled 設定 editor.minimap.enabled が true の場合に True。

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

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

特定のビューが表示されているかフォーカスされているかをチェックする when 句を持つことができます。

コンテキスト名 真の条件
view.${viewId}.visible 特定のビューが表示されている場合に True。
例: "view.workbench.explorer.fileView.visible"
focusedView 特定のビューがフォーカスされている場合に True。
例: "focusedView == 'workbench.explorer.fileView'"

ビュー識別子

  • 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 句を持つことができます。

コンテキスト名 真の条件
activeViewlet ビューコンテナがサイドバーに表示されている場合に True。
例: "activeViewlet == 'workbench.view.explorer'"
activePanel ビューコンテナがパネルに表示されている場合に True。
例: "activePanel == 'workbench.panel.output'"
activeAuxiliary ビューコンテナがセカンダリサイドバーに表示されている場合に True。
例: "activeAuxiliary == 'workbench.view.debug'"

ビューコンテナ識別子

  • 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);

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

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

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

Inspect Context Keys output

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

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

08/07/2025