when clause contexts

Visual Studio Code 會根據 VS Code UI 中可見和活動的元素，設定各種上下文鍵和特定值。這些上下文可用於選擇性地啟用或停用擴充功能命令和 UI 元素，例如選單和檢視。

例如，VS Code 使用 when clause 來啟用或停用命令快捷鍵，您可以在預設快捷鍵 JSON 中看到 (喜好設定：開啟預設鍵盤快捷鍵 (JSON))

{ "key": "f5",  "command": "workbench.action.debug.start",
                   "when": "debuggersAvailable && !inDebugMode" },

在上方，內建的 開始偵錯 命令具有快捷鍵 F5，只有在有可用的適當偵錯工具 (上下文鍵 debuggersAvailable 為 true) 且編輯器未處於偵錯模式 (上下文鍵 inDebugMode 為 false) 時才會啟用。

條件運算子

when clause 可以包含上下文鍵 (例如 inDebugMode)，或可以使用各種運算子來表達更細微的編輯器狀態。

邏輯運算子

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

關於邏輯運算子優先順序的注意事項：上表依優先順序由高至低列出運算子。範例

相等運算子

您可以檢查上下文鍵的值是否等於指定的值。請注意，右手邊是值，而不是解讀為上下文鍵，這表示不會在上下文中查閱它。

注意事項

• 如果右手邊的值是包含空格的字串，則必須以單引號括住 - "resourceFilename == 'My New File.md'"。
• === 的行為與 == 相同，而 !== 的行為與 != 相同

比較運算子

您可以將上下文鍵的值與數字進行比較。請注意，運算子的左手邊和右手邊必須以空格分隔 - foo < 1，而不是 foo<1。

比對運算子

(先前的名稱：鍵值組比對運算子)

when clause 有一個比對運算子 (=~)。表達式 key =~ regularExpressionLiteral 將右手邊視為要比對左手邊的正規表示式常值。例如，若要為所有 Docker 檔案貢獻上下文選單項目，可以使用

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

注意事項

• =~ 運算子的右手邊遵循與 JavaScript 中正規表示式常值 (參考) 相同的規則，但字元需要遵循 JSON 字串和正規表示式的逸出規則。例如，比對子字串 file:// 的正規表示式常值在 JavaScript 中會是 /file:\/\//，但在 when clause 中會是 /file:\\/\\//，因為反斜線需要在 JSON 字串中逸出，而斜線需要在正規表示式模式中逸出。
• 不存在 !=~ 運算子，但您可以否定比對表達式 - !(foo =~ /baz/)。

正規表示式旗標

可以使用旗標搭配正規表示式常值。例如，resourceFilename =~ /json/i 或 myContextKey =~ /baz/si。

支援的旗標：i、s、m、u。

忽略的旗標：g、y。

'in' 和 'not in' 條件運算子

when clause 的 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 clause，例如選單、檢視等等。

可用的上下文鍵

以下是一些可用的上下文鍵，其評估結果為布林值 true/false。

此處的清單並非詳盡無遺，您可以透過在快捷鍵編輯器 (喜好設定：開啟鍵盤快捷鍵) 中搜尋和篩選，或檢閱預設快捷鍵 JSON 檔案 (喜好設定：開啟預設鍵盤快捷鍵 (JSON)) 來尋找其他 when clause context。您也可以使用 檢查上下文鍵公用程式 來識別您感興趣使用的上下文鍵。

注意：您可以使用任何使用者或工作區設定，只要其評估結果為布林值，並加上字首 "config." 即可。

可見/焦點檢視 when clause context

您可以建立 when clause，以檢查特定的 檢視 是否為可見或具有焦點。

檢視識別碼

• 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 clause context

您可以建立 when clause，以檢查特定的 檢視容器 是否為可見

檢視容器識別碼

• 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 clause 只有在特定檢視容器具有焦點時才啟用，請將 sideBarFocus 或 panelFocus 或 auxiliaryBarFocus 與 activeViewlet 或 activePanel 或 activeAuxiliary 上下文鍵組合使用。

例如，以下 when clause 只有在檔案總管具有焦點時才為 true

"sideBarFocus && activeViewlet == 'workbench.view.explorer'"

在 when clause 中檢查設定

在 when clause 中，您可以透過在組態 (設定) 值前面加上 config. 來參考它，例如 config.editor.tabCompletion 或 config.breadcrumbs.enabled。

新增自訂 when clause context

如果您正在撰寫自己的 VS Code 擴充功能，並且需要使用 when clause context 啟用/停用命令、選單或檢視，但現有的鍵都不符合您的需求，您可以透過 setContext 命令新增自己的上下文鍵。

以下第一個範例將鍵 myExtension.showMyCommand 設定為 true，您可以在啟用命令或搭配 when 屬性時使用它。第二個範例儲存一個值，您可以使用 when clause 來檢查很酷的開啟項目數量是否大於 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 內部使用，未來可能會變更。