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 に評価される利用可能なコンテキストキーの一部です。

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

コンテキスト名 True になる条件
エディターコンテキスト
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 クイックオープン ドロップダウンがフォーカスされている。
リソースコンテキスト
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 ピークリファレンスウィンドウが開いている。
inReferenceSearchEditor ピークリファレンスウィンドウのエディターがフォーカスされている。
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 ウィンドウが禅モードである。
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 の場合、コマンドを表示するウェブビュー 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 現在アクティブなウェブビューパネルの ID。
activeCustomEditorId 現在アクティブなカスタムエディターの ID。
構成設定コンテキスト
config.editor.minimap.enabled 設定 editor.minimap.enabled が true の場合に True。

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

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

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

コンテキスト名 True になる条件
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 句を設定できます。

コンテキスト名 True になる条件
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 番目の例では、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 の要素にカーソルがハイライトされ、要素をクリックすると、現在のコンテキストキーとその状態がオブジェクトとしてコンソールに出力されます。

Inspect Context Keys output

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

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

07/09/2025