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 子句僅在檔案資源管理器獲得焦點時為真。

"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);

檢查上下文鍵實用程式

如果您想檢視執行時所有活動的上下文鍵，可以使用命令面板中的 **Developer: Inspect Context Keys** 命令 (⇧⌘P (Windows, Linux Ctrl+Shift+P))。**Inspect Context Keys** 將在 VS Code 開發者工具的 **Console** 選項卡 (Help > Toggle Developer Tools) 中顯示上下文鍵及其值。

當您執行 **Developer: Inspect Context Keys** 時，您的游標將突出顯示 VS Code UI 中的元素，當您單擊一個元素時，當前上下文鍵及其狀態將作為物件輸出到控制檯。

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

注意：一些上下文鍵供 VS Code 內部使用，並且將來可能會更改。