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 子句表示式。

關於邏輯運算子優先順序的注意事項：上表按從高到低的優先順序順序列出了運算子。示例

相等運算子

您可以檢查上下文鍵的值是否與指定值相等。請注意，右側是一個值，不解釋為上下文鍵，這意味著它不會在上下文中查詢。

備註

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

比較運算子

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

匹配運算子

（以前的名稱：鍵值對匹配運算子）

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 運算子來檢查相反的條件。

首先，確定哪些資料夾應支援該命令，並將資料夾名稱新增到陣列中。然後，使用 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 子句上下文。您還可以使用檢查上下文鍵實用程式來識別您感興趣的上下文鍵。

注意：您可以在此處使用任何評估為布林值的使用者或工作區設定，並帶字首 "config."。

可見/聚焦檢視 when 子句上下文

您可以有一個 when 子句，檢查特定檢視是否可見或聚焦。

檢視識別符號

• 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 子句，檢查特定檢視容器是否可見

檢視容器識別符號

• 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 中的元素，當您單擊一個元素時，當前的上下文鍵及其狀態將作為物件輸出到控制檯。

活動上下文鍵列表很廣泛，可能包含您已安裝的擴充套件中的自定義上下文鍵。

注意：某些上下文鍵用於 VS Code 內部使用，將來可能會更改。