现已推出！阅读 10 月份的新功能和修复。

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

运算符 符号 示例
非 ! "!editorReadonly" 或 "!(editorReadonly || inDebugMode)"
与 && "textInputFocus && !editorReadonly"
或 || "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 "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 匹配时为真。
示例："editorLangId == typescript"。
isInDiffEditor 活动编辑器是一个差异编辑器。
isInEmbeddedEditor 当焦点位于嵌入式编辑器内时为真。
操作系统上下文
isLinux 当操作系统为 Linux 时为真。
isMac 当操作系统为 macOS 时为真。
isWindows 当操作系统为 Windows 时为真。
isWeb 从 Web 访问编辑器时为真。
列表上下文
listFocus 列表具有焦点。
listSupportsMultiselect 列表支持多选。
listHasSelectionOrFocus 列表有选择或焦点。
listDoubleSelection 列表中有 2 个元素的选择。
listMultiSelection 列表有多个元素的选择。
模式上下文
inSnippetMode 编辑器处于代码段模式。
inQuickOpen 快速打开下拉菜单具有焦点。
资源上下文
resourceScheme 当资源 Uri 方案匹配时为真。
示例："resourceScheme == file"
resourceFilename 当资源管理器或编辑器文件名匹配时为真。
示例："resourceFilename == gulpfile.js"
resourceExtname 当资源管理器或编辑器文件名扩展名匹配时为真。
示例："resourceExtname == .js"
resourceDirname 当资源管理器或编辑器的资源绝对文件夹路径匹配时为真。
示例："resourceDirname == /users/alice/project/src"
resourcePath 当资源管理器或编辑器的资源绝对路径匹配时为真。
示例："resourcePath == /users/alice/project/gulpfile.js"
resourceLangId 当资源管理器或编辑器标题的 语言 ID 匹配时为真。
示例："resourceLangId == markdown"
isFileSystemResource 当资源管理器或编辑器文件是文件系统资源，可以由文件系统提供者处理时为真。
resourceSet 当资源管理器或编辑器文件已设置时为真。
resource 资源管理器或编辑器文件的完整 Uri。
资源管理器上下文
explorerViewletVisible 如果资源管理器视图可见，则为真。
explorerViewletFocus 如果资源管理器视图具有键盘焦点，则为真。
filesExplorerFocus 如果文件资源管理器部分具有键盘焦点，则为真。
openEditorsFocus 如果打开的编辑器部分具有键盘焦点，则为真。
explorerResourceIsFolder 如果在资源管理器中选择了文件夹，则为真。
编辑器小部件上下文
findWidgetVisible 编辑器查找小部件可见。
suggestWidgetVisible 建议小部件（IntelliSense）可见。
suggestWidgetMultipleSuggestions 显示了多个建议。
renameInputVisible 重命名输入文本框可见。
referenceSearchVisible 快速查看引用弹出窗口已打开。
inReferenceSearchEditor 快速查看引用弹出窗口编辑器已获得焦点。
config.editor.stablePeek 保持弹出编辑器处于打开状态（由editor.stablePeek设置控制）。
codeActionMenuVisible 代码操作菜单可见。
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 通知提示在 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 当窗口处于全屏状态时为真。
focusedView 当前获得焦点的视图的标识符。
canNavigateBack 如果可以向后导航，则为真。
canNavigateForward 如果可以向前导航，则为真。
canNavigateToLastEditLocation 如果可以导航到上次编辑的位置，则为真。
全局编辑器 UI 上下文
textCompareEditorVisible 至少有一个 diff（比较）编辑器可见。
textCompareEditorActive diff（比较）编辑器处于活动状态。
editorIsOpen 如果有一个编辑器已打开，则为真。
groupEditorsCount 组中编辑器的数量。
activeEditorGroupEmpty 如果活动编辑器组没有编辑器，则为真。
activeEditorGroupIndex 从1 开始的数字，反映编辑器组在编辑器网格中的位置。
索引为1 的组将是左上角的第一个组。
activeEditorGroupLast 对于编辑器网格中的最后一个编辑器组，将为true。
multipleEditorGroups 当存在多个编辑器组时为真。
activeEditor 组中活动编辑器的标识符。
activeEditorIsDirty 当组中的活动编辑器已修改时为真。
activeEditorIsNotPreview 当组中的活动编辑器未处于预览模式时为真。
activeEditorIsPinned 当组中的活动编辑器已固定时为真。
inSearchEditor 当焦点位于搜索编辑器内时为真。
activeWebviewPanelId 当前活动的webview 面板 的 ID。
activeCustomEditorId 当前活动的 自定义编辑器 的 ID。
配置设置上下文
config.editor.minimap.enabled 当设置editor.minimap.enabled 为true 时为真。

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

可见/聚焦视图 when 子句上下文

您可以拥有一个 when 子句，用于检查特定 视图 是否可见或已获得焦点。

上下文名称 在什么情况下为 true
view.${viewId}.visible 当特定视图可见时为真。
示例："view.workbench.explorer.fileView.visible"
focusedView 当特定视图已获得焦点时为真。
示例："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 当视图容器在侧边栏中可见时为真。
示例："activeViewlet == 'workbench.view.explorer'"
activePanel 当视图容器在面板中可见时为真。
示例："activePanel == 'workbench.panel.output'"
activeAuxiliary 当视图容器在辅助侧边栏中可见时为真。
示例："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 子句仅在文件资源管理器获得焦点时为真

"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 内部使用，将来可能会更改。

10/29/2024