VSCode when 子句上下文Visual Studio Code 根据 VS Code UI 中可见和活动的元素设

Visual Studio Code 根据 VS Code UI 中可见和活动的元素设置各种上下文键和特定值。这些上下文可用于选择性地启用或禁用扩展命令和 UI 元素，例如菜单和视图。

例如，VS Code 使用 when 子句来启用或禁用命令键绑定，您可以在 Default Keybindings JSON (Preferences: Open Default Keyboard Shortcuts (JSON)) 中看到：

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

内置的 Start Debugging 命令上方有键盘快捷键 F5，该快捷键仅在有适当的调试器可用（context debuggersAvailable 为 true）且编辑器未处于调试模式（context inDebugMode 为 false）时启用。

官网文档

条件运算符

Operator	Symbol	Example
等于	`==`	`"editorLangId == typescript"`
不等于	`!=`	`"resourceExtname != .js"`
逻辑或	`\|\|`	`"isLinux \|\| isWindows"`
逻辑与	`&&`	`"textInputFocus && !editorReadonly"`
非	`!`	`"!editorReadonly"`
Matches 正则匹配	`!`	`"resourceScheme =~ /^untitled$\|^file$/"`
大于、大于等于	`> >=`	`"gitOpenRepositoryCount >= 1"`
小于、小于等于	`< <=`	`"workspaceFolderCount <= 2"`
In	`in`	`"resourceFilename in supportedFolders"`详情如下

key-value 的 when 子句运算符

when 子句有一个键值对匹配运算符。表达式 key =~ value 将右侧视为正则表达式以匹配左侧。例如，要为所有 Docker 文件提供上下文菜单项，可以使用：

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

此处的列表并不详尽，您可以通过在键盘快捷键编辑器中搜索和过滤找到其他 when 子句上下文（Preferences: Open Keyboard Shortcuts）或查看默认键绑定 JSON 文件（Preferences: Open Default Keyboard Shortcuts (JSON)）。

Context name	True when
编辑器相关
`editorFocus`	编辑器具有焦点，文本或小部件。
`editorTextFocus`	编辑器中的文本具有焦点（光标闪烁）。
`textInputFocus`	任何编辑器有焦点（常规编辑器、调试 REPL 等）。
`inputFocus`	任何文本输入区域有焦点（编辑器或文本框）。
`editorHasSelection`	在编辑器中选择文本。
`editorHasMultipleSelections`	选择了多个文本区域（多个光标）。
`editorReadonly`	编辑器是只读的。
`editorLangId`	当编辑器的关联 language ID 匹配时为真。示例：`"editorLangId == typescript"`。
`isInDiffEditor`	活动编辑器是差异编辑器。
`isInEmbeddedEditor`	当焦点位于嵌入式编辑器内时为真。
操作系统相关
`isLinux`	操作系统是 Linux
`isMac`	操作系统是 Mac
`isWindows`	操作系统是 Windows
`isWeb`	从 Web 访问编辑器
模式上下文
`inSnippetMode`	编辑器处于片段模式。
`inQuickOpen`	快速打开下拉菜单具有焦点。
资源上下文
`resourceScheme`	当资源 Uri scheme 匹配时为真。示例：`"resourceScheme == file"`
`resourceFilename`	当资源管理器或编辑器文件名匹配时为真。例子：`"resourceFilename == gulpfile.js"`
`resourceExtname`	当资源管理器或编辑器文件扩展名匹配时为真。例子：`"resourceExtname == .js"`
`resourceDirname`	当资源管理器或编辑器的资源绝对文件夹路径匹配时为真。例子：`"resourcePath == /users/alice/project/gulpfile.js"`
`resourceLangId`	当资源管理器或编辑器标题 language ID 匹配时为真。例子：`"resourceLangId == markdown"`
`resourceLangId`	当资源管理器或编辑器标题 language ID 匹配时为真。例子：`"resourceLangId == markdown"`
`isFileSystemResource`	当资源管理器或编辑器文件是可以从文件系统提供程序处理的文件系统资源时为真
`resourceSet`	设置资源管理器或编辑器文件时为真
`resource`	Explorer 或编辑器文件的完整 Uri
资源管理器上下文
`explorerViewletVisible`	如果资源管理器视图可见，则为真。
`explorerViewletFocus`	如果资源管理器视图具有键盘焦点，则为真。
`filesExplorerFocus`	如果文件资源管理器部分具有键盘焦点，则为真。
`openEditorsFocus`	如果 OPEN EDITORS 部分具有键盘焦点，则为真。
`explorerResourceIsFolder`	如果在资源管理器中选择了文件夹，则为真。
编辑器小部件上下文
`findWidgetVisible`	编辑器查找小部件可见。
`suggestWidgetVisible`	建议小部件 (IntelliSense) 可见。
`suggestWidgetMultipleSuggestions`	显示多个建议。
`renameInputVisible`	重命名输入文本框可见。
`referenceSearchVisible`	Peek References 预览窗口打开。
`inReferenceSearchEditor`	Peek References peek 窗口编辑器具有焦点。
`config.editor.stablePeek`	保持 peek 编辑器打开（由 `editor.stablePeek` 设置控制）。
`quickFixWidgetVisible`	快速修复小部件可见。
`parameterHintsVisible`	参数提示是可见的（由 editor.parameterHints.enabled 设置控制）。
`parameterHintsMultipleSignatures`	显示多个参数提示。
调试器上下文
`debuggersAvailable`	有适当的调试器扩展可用。
`inDebugMode`	调试会话正在运行。
`debugState`	活动调试器状态。可能的值是 `inactive`, `initializing`, `stopped`, `running`。
`debugType`	当调试类型匹配时为真。示例：`"debugType == 'node'"`。
`inDebugRepl`	焦点在调试控制台 REPL。
集成终端上下文
`terminalFocus`	集成终端具有焦点。
`terminalIsOpen`	打开一个集成终端。
时间线视图上下文
`timelineFollowActiveEditor`	如果时间轴视图跟随活动编辑器，则为真。
时间线视图项目上下文
`timelineItem`	当时间线项目的上下文值匹配时为真。示例：`"timelineItem =~ /git:file:commit\\b/"`。
扩展上下文
`extension`	当扩展程序的 ID 匹配时为真。示例：`"extension == eamodio.gitlens"`。
`extensionStatus`	安装扩展时为真。示例：`"extensionStatus == installed"`。
`extensionHasConfiguration`	如果扩展有配置，则为真。
全局 UI 上下文
`notificationFocus`	通知具有键盘焦点。
`notificationCenterVisible`	通知中心在 VS Code 的右下角可见。
`notificationToastsVisible`	通知 toast 在 VS Code 的右下角可见。
`searchViewletVisible`	搜索视图已打开。
`sideBarVisible`	显示侧边栏。
`sideBarFocus`	侧边栏有焦点。
`panelFocus`	Panel 有焦点。
`inZenMode`	窗口处于 Zen 模式。
`isCenteredLayout`	编辑器处于居中布局模式。
`workbenchState`	Can be `empty`, `folder` (1 folder), or `workspace`.
`workspaceFolderCount`	工作区文件夹的计数。
`replaceActive`	搜索视图替换文本框打开。
`view`	当视图标识符匹配时为真。例子： `"view == myViewsExplorerID"`。
`viewItem`	当 viewItem 上下文匹配时为真。例子： `"viewItem == someContextValue"`。
`isFullscreen`	当窗口全屏时为真。
`focusedView`	当前焦点视图的标识符。
`canNavigateBack`	如果可以返回，则为真。
`canNavigateForward`	如果可以向前导航，则为真。
`canNavigateToLastEditLocation`	如果可以导航到最后一个编辑位置，则为真。
全局编辑器 UI 上下文
`textCompareEditorVisible`	至少一个差异（比较）编辑器是可见的。
`textCompareEditorActive`	差异（比较）编辑器处于活动状态。
`editorIsOpen`	如果一个编辑器打开，则为真。
`groupEditorsCount`	辑器分组中的辑器的数量。
`activeEditorGroupEmpty`	如果活动编辑器组没有编辑器，则为真。
`activeEditorGroupIndex`	从 1 开始的数字，反映编辑器组在编辑器网格中的位置。索引为 1 的组将位于左上角的第一个。
`activeEditorGroupLast`	将适用于编辑器网格中的最后一个编辑器组。
`multipleEditorGroups`	当存在多个编辑器组时为真。
`activeEditor`	组中活动编辑器的标识符。
`activeEditorIsDirty`	当组中的活动编辑器脏时为真。
`activeEditorIsNotPreview`	当组中的活动编辑器未处于预览模式时为真。
`activeEditorIsPinned`	当组中的活动编辑器被固定时为真。
`inSearchEditor`	当焦点位于搜索编辑器内时为真。
配置设置上下文
`config.editor.minimap.enabled`	当设置 `editor.minimap.enabled` 为真时为真。

注意：您可以使用任何用户或工作区设置，在此处计算为布尔值并带有前缀 "config."。

Active/focused 视图或面板的 when 子句上下文

Context name	True when
`activeViewlet`	当视图可见时为真。例子： `"activeViewlet == 'workbench.view.explorer'"`
`activePanel`	面板可见时为真。例子： `"activePanel == 'workbench.panel.output'"`
`focusedView`	当视图聚焦时为真。示例： `"focusedView == myViewsExplorerID"`

View Identifiers:

workbench.view.explorer - File Explorer
workbench.view.search - Search
workbench.view.scm - Source Control
workbench.view.debug - Run
workbench.view.extensions - Extensions

Panel Identifiers:

workbench.panel.markers - Problems
workbench.panel.output - Output
workbench.panel.repl - Debug Console
terminal - Integrated Terminal
workbench.panel.comments - Comments
workbench.view.search - Search when search.location is set to panel

如果您想要一个仅在特定视图或面板具有焦点时启用的 when 子句，请将 sideBarFocus 或 panelFocus 与 activeViewlet 或 activePanel 结合使用。例如，下面的 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);

'in' 条件运算符

when 子句的 in 运算符允许在另一个上下文 key's value 中动态查找上下文 key's value。例如，如果您想将上下文菜单命令添加到包含某种类型文件（或无法静态知道的文件）的文件夹中，您现在可以使用 in 运算符来实现它。

首先，确定哪些文件夹应该支持该命令，并将文件夹名称设置为一个数组。然后，使用 setContext 命令将数组转换为上下文 key：

vscode.commands.executeCommand('setContext', 'ext.supportedFolders', [
  'test',
  'foo',
  'bar'
]);

// or

// 注意在这种情况下（使用对象），值无关紧要，它是基于对象中键的存在
// The value must be of a simple type
vscode.commands.executeCommand('setContext', 'ext.supportedFolders', {
  test: true,
  foo: 'anything',
  bar: false
});

然后，在 package.json 中，您可以为 explorer/context 菜单添加菜单贡献：

// 注意，这假设您已经定义了一个名为 ext.doSpecial 的命令
"menus": {
  "explorer/context": [
    {
      "command": "ext.doSpecial",
      "when": "explorerResourceIsFolder && resourceFilename in ext.supportedFolders"
    }
  ]
}

在该示例中，我们获取 resourceFilename 的值（在本例中为文件夹的名称）并检查其是否存在于 ext.supportedFolders 的值中。如果存在，将显示菜单。这个强大的运算符应该允许更丰富的条件和动态贡献，以支持 when 子句，例如菜单、视图等。

检查上下文 Keys 效用

如果您想在运行时查看所有当前活动的上下文 keys，您可以使用 Developer: Inspect Context Keys 命令 (Ctrl+Shift+P)。 Inspect Context Keys 将在 VS Code 开发人员工具 Console tab (Help > Toggle Developer Tools) 中显示上下文 keys 及其 values。

当您运行 Developer: Inspect Context Keys 时，您的光标将突出显示 VS Code UI 中的元素，当您单击一个元素时，当前的上下文键及其状态将作为对象输出到控制台。

活动上下文键的列表很广泛，可能包含您已安装的扩展的自定义上下文键。

注意：某些上下文键供 VS Code 内部使用，将来可能会更改。

附录

都看到这里了，还不点个赞吗？
消化官方内容不易，希望对你有所帮助。
后续会持续更新相关的学习内容，并将最新的文档链接附到此处。