在 VS Code 中尝试！

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）组成，也可以使用各种运算符来表达更细微的编辑器状态。

逻辑运算符

逻辑运算符允许组合简单的上下文键或 when 子句表达式，这些表达式可以包含其他逻辑运算符、相等运算符、比较运算符、匹配运算符、in/not in 运算符或带括号的表达式。

运算符 符号 示例
非 (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 当操作系统是 Linux 时为 True。
isMac 当操作系统是 macOS 时为 True。
isWindows 当操作系统是 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。
编辑器小部件上下文
findWidgetVisible 编辑器查找小部件可见。
suggestWidgetVisible 建议小部件（智能感知）可见。
suggestWidgetMultipleSuggestions 显示了多个建议。
renameInputVisible 重命名输入文本框可见。
referenceSearchVisible 查看引用 Peek 窗口已打开。
inReferenceSearchEditor 查看引用 Peek 窗口编辑器具有焦点。
config.editor.stablePeek 保持 Peek 编辑器打开（由 editor.stablePeek 设置控制）。
codeActionMenuVisible 代码操作菜单可见。
parameterHintsVisible 参数提示可见（由 editor.parameterHints.enabled 设置控制）。
parameterHintsMultipleSignatures 显示了多个参数提示。
调试器上下文
debuggersAvailable 有适当的调试器扩展可用。
inDebugMode 调试会话正在运行。
debugState 活动调试器状态。
可能的值为 inactive（非活动）、initializing（初始化中）、stopped（已停止）、running（正在运行）。
debugType 当调试类型匹配时为 True。
示例："debugType == 'node'"。
inDebugRepl 焦点在调试控制台 REPL 中。
集成终端上下文
terminalFocus 集成终端具有焦点。
terminalIsOpen 集成终端已打开。
时间轴视图上下文
timelineFollowActiveEditor 如果时间轴视图正在跟随活动编辑器则为 True。
时间轴视图项上下文
timelineItem 当时间轴项的上下文值匹配时为 True。
示例："timelineItem =~ /git:file:commit\\b/"。
扩展上下文
extension 当扩展 ID 匹配时为 True。
示例："extension == eamodio.gitlens"。
extensionStatus 当扩展已安装时为 True。
示例："extensionStatus == installed"。
extensionHasConfiguration 如果扩展具有配置则为 True。
全局 UI 上下文
notificationFocus 通知具有键盘焦点。
notificationCenterVisible 通知中心在 VS Code 右下角可见。
notificationToastsVisible 通知 Toast 在 VS Code 右下角可见。
searchViewletVisible 搜索视图已打开。
sideBarVisible 侧边栏已显示。
sideBarFocus 侧边栏具有焦点。
panelFocus 面板具有焦点。
inZenMode 窗口处于 Zen 模式。
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"。
isFullscreen 当窗口处于全屏模式时为 True。
focusedView 当前聚焦视图的标识符。
canNavigateBack 如果可以向后导航则为 True。
canNavigateForward 如果可以向前导航则为 True。
canNavigateToLastEditLocation 如果可以导航到上次编辑位置则为 True。
全局编辑器 UI 上下文
textCompareEditorVisible 至少有一个 diff (比较) 编辑器可见。
textCompareEditorActive 一个 diff (比较) 编辑器处于活动状态。
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 开发人员工具的**控制台**标签页（**帮助** > **切换开发人员工具**）中显示上下文键及其值。

运行**开发人员: 检查上下文键**时，光标将高亮显示 VS Code UI 中的元素，当你单击一个元素时，当前的上下文键及其状态将作为对象输出到控制台。

Inspect Context Keys output

活动上下文键的列表很详尽，并且可能包含你已安装扩展的自定义上下文键。

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

06/12/2025