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

关于逻辑运算符优先级的注意事项：上表按从高到低的优先级顺序列出了运算符。示例

相等运算符

您可以检查上下文键的值是否与指定值相等。请注意，右侧是一个值，不被解释为上下文键，这意味着它不会在上下文中查找。

备注

• 如果右侧的值是包含空格的字符串，则必须用单引号括起来 - "resourceFilename == 'My New File.md'"。
• === 与 == 行为相同，!== 与 != 行为相同

比较运算符

您可以将上下文键的值与数字进行比较。请注意，运算符的左右两侧必须用空格分隔 - foo < 1，但不能是 foo<1。

匹配运算符

(以前的名称：键值对匹配运算符)

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 运算符来检查相反的条件。

首先，确定哪些文件夹应支持该命令，并将文件夹名称添加到数组中。然后，使用 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 子句上下文。您还可以使用 检查上下文键实用程序 来识别您感兴趣的上下文键。

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

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

您可以有一个 when 子句，它检查特定 视图 是否可见或聚焦。

视图标识符

• 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 子句，它检查特定 视图容器 是否可见

视图容器标识符

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