when 子句上下文
Visual Studio Code 会根据 VS Code 用户界面中哪些元素是可见且活动的，来设置各种上下文键和特定的值。这些上下文可用于有选择地启用或禁用扩展命令以及菜单、视图等 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）组成，也可以使用各种运算符来表达更细致的编辑器状态。
逻辑运算符
逻辑运算符允许组合简单的上下文键或包含其他逻辑、相等、比较、匹配、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 字符串和正则表达式的转义规则。例如，在 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。 |
| 源代码管理上下文 | |
scmProvider |
当源代码管理提供程序 ID 匹配时为 True。 示例： "scmProvider == git"。 |
scmResourceGroup |
当源代码管理资源组 ID 匹配时为 True。 示例： "scmResourceGroup == merge"。 |
originalResourceScheme |
当快速差异编辑器中的原始资源方案匹配时为 True。 示例： "originalResourceScheme == git"。 |
| 编辑器小组件上下文 | |
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 |
集成终端已打开。 |
| 任务执行上下文 | |
shellExecutionSupported |
当 VS Code 可以运行 ShellExecution 任务时为 True。 |
processExecutionSupported |
当 VS Code 可以运行 ProcessExecution 任务时为 True。 |
customExecutionSupported |
当 VS Code 可以运行 CustomExecution 任务时为 True。 |
| 时间线视图上下文 | |
timelineFollowActiveEditor |
如果时间线视图正在跟随活动编辑器，则为 True。 |
| 时间线视图项上下文 | |
timelineItem |
当时间线项的上下文值匹配时为 True。 示例： "timelineItem =~ /git:file:commit\\b/"。 |
| 扩展上下文 | |
extension |
当扩展 ID 匹配时为 True。 示例： "extension == eamodio.gitlens"。 |
extensionStatus |
当扩展已安装时为 True。 示例： "extensionStatus == installed"。 |
extensionHasConfiguration |
如果扩展具有配置，则为 True。 |
| 测试上下文 | |
testId |
当当前测试项 ID 匹配时为 True。 |
controllerId |
当当前测试控制器 ID 匹配时为 True。 |
testing.testItemHasUri |
当当前测试项与 URI 关联时为 True。 |
| 工作区上下文 | |
virtualWorkspace |
当当前工作区使用虚拟文件系统时为 True。 |
isWorkspaceTrusted |
当当前工作区受信任时为 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"。 |
webviewSection |
对于 webview/context，为显示命令的 webview 部分。示例： "webviewSection == 'editor'"。 |
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 子句，用于检查特定的视图是否可见或具有焦点。
| 上下文名称 | 为 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 中的元素，当你单击某个元素时，当前的上下文键及其状态将作为对象输出到控制台中。
活动上下文键的列表非常广泛，并且可能包含来自你已安装的扩展的自定义上下文键。
注意：某些上下文键供 VS Code 内部使用，将来可能会更改。