探索智能体开发 -

when 子句上下文

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

例如，VS Code 使用 when 子句来启用或禁用命令快捷键，您可以在“默认快捷键 JSON”（首选项：打开默认键盘快捷方式 (JSON)）中看到这一点。

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

如上所示，内置的 Start Debugging 命令的快捷键是 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 字符串和正则表达式的转义规则。例如，在 JavaScript 中匹配子字符串 file:// 的正则表达式字面量是 /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 "resourceFilename in supportedFolders"
不包含 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 方案匹配时为 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 建议小部件（IntelliSense）可见。
suggestWidgetMultipleSuggestions 显示了多个建议。
renameInputVisible 重命名输入文本框可见。
referenceSearchVisible “速览引用”（Peek References）窗口已打开。
inReferenceSearchEditor “速览引用”窗口的编辑器获得焦点。
config.editor.stablePeek 保持速览编辑器打开（由 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 时间轴项的 contextValue 匹配时为 true。
示例："timelineItem =~ /git:file:commit\\b/"。
扩展上下文
extension 扩展 ID 匹配时为 true。
示例："extension == eamodio.gitlens"。
extensionStatus 扩展已安装时为 true。
示例："extensionStatus == installed"。
extensionHasConfiguration 如果扩展有配置，则为 true。
全局 UI 上下文
notificationFocus 通知具有键盘焦点。
notificationCenterVisible 通知中心在 VS Code 右下角可见。
notificationToastsVisible 通知提示在 VS Code 右下角可见。
searchViewletVisible 搜索视图已打开。
sideBarVisible 侧边栏已显示。
sideBarFocus 侧边栏获得焦点。
panelFocus 面板获得焦点。
inZenMode 窗口处于禅模式。
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 至少有一个差异（比较）编辑器可见。
textCompareEditorActive 差异（比较）编辑器处于活动状态。
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 子句上下文

您可以编写一个检查特定 View 是否可见或获得焦点的 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);

“检查上下文键”工具

如果您想在运行时查看所有当前活动的上下文键，可以使用命令面板中的 Developer: Inspect Context Keys 命令（⇧⌘P（Windows, Linux 为 Ctrl+Shift+P））。Inspect Context Keys 将在 VS Code 开发人员工具的 Console 选项卡（帮助 > 切换开发人员工具）中显示上下文键及其值。

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

Inspect Context Keys output

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

注意：某些上下文键供 VS Code 内部使用，未来可能会发生变化。

4/8/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.