💻 歡迎參加 6 月 3 日舉行的 MS Build 之 VS Code 直播活動。

when 子句上下文

Visual Studio Code 會根據 VS Code UI 中哪些元素可見且處於作用中狀態，來設定各種內容金鑰（context keys）與特定值。這些上下文可用於選擇性地啟用或停用擴充功能指令與 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 子句中必須寫為 /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 當 OS 為 Linux 時為 True。
isMac 當 OS 為 macOS 時為 True。
isWindows 當 OS 為 Windows 時為 True。
isWeb 當從 Web 存取編輯器時為 True。
列表上下文
listFocus 列表獲得焦點。
listSupportsMultiselect 列表支援多重選取。
listHasSelectionOrFocus 列表有選取項目或獲得焦點。
listDoubleSelection 列表選取了 2 個元素。
listMultiSelection 列表選取了多個元素。
模式上下文
inSnippetMode 編輯器處於程式碼片段模式。
inQuickOpen 快速開啟下拉式選單獲得焦點。
資源上下文
resourceScheme 當資源 Uri 配置（scheme）符合時為 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。
原始碼控制上下文
scmProvider 當原始碼控制提供者 ID 符合時為 True。
範例："scmProvider == git"。
scmResourceGroup 當原始碼控制資源群組 ID 符合時為 True。
範例："scmResourceGroup == merge"。
originalResourceScheme 當快速差異（Quick Diff）編輯器中的原始資源配置符合時為 True。
範例："originalResourceScheme == git"。
編輯器小工具上下文
findWidgetVisible 編輯器搜尋小工具可見。
suggestWidgetVisible 建議小工具 (IntelliSense) 可見。
suggestWidgetMultipleSuggestions 顯示多個建議。
renameInputVisible 重新命名輸入文字方塊可見。
referenceSearchVisible 「查看參照」視窗已開啟。
inReferenceSearchEditor 「查看參照」視窗的編輯器獲得焦點。
config.editor.stablePeek 保持查看編輯器開啟（由 editor.stablePeek 設定控制）。
codeActionMenuVisible 程式碼動作（Code Action）選單可見。
parameterHintsVisible 參數提示可見（由 editor.parameterHints.enabled 設定控制）。
parameterHintsMultipleSignatures 顯示多個參數提示。
偵錯器上下文
debuggersAvailable 有合適的偵錯器擴充功能可用。
inDebugMode 偵錯工作階段正在執行。
debugState 作用中偵錯器的狀態。
可能的值為 inactive (非作用中)、initializing (初始化中)、stopped (已停止)、running (執行中)。
debugType 當偵錯類型符合時為 True。
範例："debugType == 'node'"。
inDebugRepl 焦點位於偵錯主控台 REPL 中。
整合式終端機上下文
terminalFocus 整合式終端機獲得焦點。
terminalIsOpen 已開啟整合式終端機。
工作執行上下文
shellExecutionSupported 當 VS Code 可以執行 ShellExecution 工作時為 True。
processExecutionSupported 當 VS Code 可以執行 ProcessExecution 工作時為 True。
customExecutionSupported 當 VS Code 可以執行 CustomExecution 工作時為 True。
時間軸檢視上下文
timelineFollowActiveEditor 如果時間軸檢視正在跟隨作用中編輯器，則為 True。
時間軸檢視項目上下文
timelineItem 當時間軸項目的內容值符合時為 True。
範例："timelineItem =~ /git:file:commit\\b/"。
擴充功能上下文
extension 當擴充功能的 ID 符合時為 True。
範例："extension == eamodio.gitlens"。
extensionStatus 當擴充功能已安裝時為 True。
範例："extensionStatus == installed"。
extensionHasConfiguration 如果擴充功能有設定，則為 True。
測試上下文
testId 當目前的測試項目 ID 符合時為 True。
controllerId 當目前的測試控制器 ID 符合時為 True。
testing.testItemHasUri 當目前的測試項目與 URI 關聯時為 True。
工作區上下文
virtualWorkspace 當目前工作區使用虛擬檔案系統時為 True。
isWorkspaceTrusted 當目前工作區受信任時為 True。
全域 UI 上下文
notificationFocus 通知獲得鍵盤焦點。
notificationCenterVisible 通知中心在 VS Code 右下角可見。
notificationToastsVisible 通知快顯（toast）在 VS Code 右下角可見。
searchViewletVisible 搜尋檢視已開啟。
sideBarVisible 側邊欄已顯示。
sideBarFocus 側邊欄獲得焦點。
panelFocus 面板獲得焦點。
inZenMode 視窗處於禪模式（Zen Mode）。
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"。
webviewSection 對於 webview/context，為指令要顯示的 Webview 區段。
範例："webviewSection == 'editor'"。
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 當群組中的作用中編輯器為髒（未儲存）狀態時為 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 開發人員工具的主控台 (Console) 索引標籤（說明 > 切換開發人員工具）中顯示內容金鑰及其值。

當您執行開發人員：檢查內容金鑰時，您的游標將會反白顯示 VS Code UI 中的元素；當您點擊某個元素時，目前的內容金鑰及其狀態將會以物件形式輸出至主控台。

Inspect Context Keys output

作用中的內容金鑰列表非常詳盡，可能包含您已安裝之擴充功能的自訂內容金鑰。

注意：某些內容金鑰為 VS Code 內部使用，未來可能會有所變更。

5/28/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.