尝试以扩展 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 运算符或括号表达式。

运算符 符号 示例
! "!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/imyContextKey =~ /baz/si

支持的标志:ismu

忽略的标志:gy

'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 “查看引用”速览窗口已打开。
inReferenceSearchEditor “查看引用”速览窗口编辑器有焦点。
config.editor.stablePeek 保持速览编辑器打开(由 editor.stablePeek 设置控制)。
codeActionMenuVisible 代码操作菜单可见。
parameterHintsVisible 参数提示可见(由 editor.parameterHints.enabled 设置控制)。
parameterHintsMultipleSignatures 显示多个参数提示。
调试器上下文
debuggersAvailable 有可用的相应调试器扩展。
inDebugMode 正在运行调试会话。
debugState 活动调试器状态。
可能的值是 inactiveinitializingstoppedrunning
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 可以是 emptyfolder(1 个文件夹)或 workspace
workspaceFolderCount 工作区文件夹的数量。
replaceActive 搜索视图的替换文本框已打开。
view 对于 view/titleview/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.enabledtrue 时为 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 子句,请结合使用 sideBarFocuspanelFocusauxiliaryBarFocusactiveViewletactivePanelactiveAuxiliary 上下文键。

例如,以下 when 子句仅在文件资源管理器具有焦点时为 True

"sideBarFocus && activeViewlet == 'workbench.view.explorer'"

在 when 子句中检查设置

在 when 子句中,可以通过前缀 config. 来引用配置(设置)值,例如 config.editor.tabCompletionconfig.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 内部使用,将来可能会更改。