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/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 子句上下文。你还可以使用检查上下文键实用工具来识别你感兴趣的上下文键。
上下文名称 | 为真时 |
---|---|
编辑器上下文 | |
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 |
活动调试器状态。 可能的值为 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 |
窗口处于禅模式。 |
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 子句上下文
你可以使用 when 子句来检查特定的视图是否可见或聚焦。
上下文名称 | 为真时 |
---|---|
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 子句来检查特定的视图容器是否可见
上下文名称 | 为真时 |
---|---|
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 中的元素,当你单击元素时,当前上下文键及其状态将作为对象输出到控制台。
活动上下文键的列表非常广泛,可能包含你已安装的扩展的自定义上下文键。
注意:某些上下文键供 VS Code 内部使用,将来可能会更改。