🚀 在 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)，或可以使用各種運算子來表達更細微的編輯器狀態。

邏輯運算子

邏輯運算子允許組合簡單的上下文索引鍵或 when 條款運算式，其中包含其他邏輯、相等、比較、比對、in/not in 運算子或括號括住的運算式。

運算子 符號 範例
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 條款中會是 /file:\\/\\//，因為反斜線需要在 JSON 字串中逸出，而斜線需要在規則運算式模式中逸出。
  • 沒有 !=~ 運算子，但您可以否定比對運算式 - !(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 條款，例如選單、檢視等等。

可用的上下文索引鍵

以下是一些可用的上下文索引鍵，其評估結果為布林值 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 當作業系統為 Linux 時為 True。
isMac 當作業系統為 macOS 時為 True。
isWindows 當作業系統為 Windows 時為 True。
isWeb 從 Web 存取編輯器時為 True。
清單上下文
listFocus 清單具有焦點。
listSupportsMultiselect 清單支援多重選取。
listHasSelectionOrFocus 清單具有選取項目或焦點。
listDoubleSelection 清單具有 2 個元素的選取項目。
listMultiSelection 清單具有多個元素的選取項目。
模式上下文
inSnippetMode 編輯器處於程式碼片段模式。
inQuickOpen 快速開啟下拉式選單具有焦點。
資源上下文
resourceScheme 當資源 Uri 結構描述符合時為 True。
範例："resourceScheme == file"
resourceFilename 當 Explorer 或編輯器檔案名稱符合時為 True。
範例："resourceFilename == gulpfile.js"
resourceExtname 當 Explorer 或編輯器檔案名稱副檔名符合時為 True。
範例："resourceExtname == .js"
resourceDirname 當 Explorer 或編輯器的資源絕對資料夾路徑符合時為 True。
範例："resourceDirname == /users/alice/project/src"
resourcePath 當 Explorer 或編輯器的資源絕對路徑符合時為 True。
範例："resourcePath == /users/alice/project/gulpfile.js"
resourceLangId 當 Explorer 或編輯器標題 語言 ID 符合時為 True。
範例："resourceLangId == markdown"
isFileSystemResource 當 Explorer 或編輯器檔案是可從檔案系統提供者處理的檔案系統資源時為 True。
resourceSet 當已設定 Explorer 或編輯器檔案時為 True。
resource Explorer 或編輯器檔案的完整 Uri。
Explorer 上下文
explorerViewletVisible 如果 Explorer 檢視可見則為 True。
explorerViewletFocus 如果 Explorer 檢視具有鍵盤焦點則為 True。
filesExplorerFocus 如果檔案總管區段具有鍵盤焦點則為 True。
openEditorsFocus 如果開啟的編輯器區段具有鍵盤焦點則為 True。
explorerResourceIsFolder 如果在 Explorer 中選取資料夾則為 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，要在其中顯示命令的 webview ID。
範例："webviewId == catCoding"。
isFullscreen 當視窗處於全螢幕時為 True。
focusedView 目前已聚焦檢視的識別碼。
canNavigateBack 如果可以返回導覽則為 True。
canNavigateForward 如果可以向前導覽則為 True。
canNavigateToLastEditLocation 如果可以導覽至上次編輯位置則為 True。
全域編輯器 UI 上下文
textCompareEditorVisible 至少有一個差異 (比較) 編輯器可見。
textCompareEditorActive 差異 (比較) 編輯器為作用中。
editorIsOpen 如果已開啟一個編輯器則為 True。
groupEditorsCount 群組中的編輯器數量。
activeEditorGroupEmpty 如果作用中編輯器群組沒有編輯器則為 True。
activeEditorGroupIndex 從 1 開始的數字，反映編輯器網格中編輯器群組的位置。
索引 1 的群組將是左上角的第一個群組。
activeEditorGroupLast 對於編輯器網格中的最後一個編輯器群組，將為 true。
multipleEditorGroups 當存在多個編輯器群組時為 True。
activeEditor 群組中作用中編輯器的識別碼。
activeEditorIsDirty 當群組中的作用中編輯器為 dirty 時為 True。
activeEditorIsNotPreview 當群組中的作用中編輯器未處於預覽模式時為 True。
activeEditorIsPinned 當群組中的作用中編輯器為釘選時為 True。
inSearchEditor 當焦點在搜尋編輯器內時為 True。
activeWebviewPanelId 目前作用中 webview 面板的 ID。
activeCustomEditorId 目前作用中 自訂編輯器的 ID。
設定設定上下文
config.editor.minimap.enabled 當設定 editor.minimap.enabled 為 true 時為 True。

注意：您可以在此處使用任何評估結果為布林值的使用者或工作區設定，並加上前置字元 "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 屬性中使用它。第二個範例儲存一個值，您可以使用 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 內部使用，未來可能會變更。

04/03/2025