when 子句上下文

VS Code 为元素是否处于可见和激活状态，设置了不同的上下文值。这些上下文可以禁用或者启用插件的某些命令和 UI 元素，比如菜单和视图。

比如，VS Code 用 when 子句启停命令快捷键，你可以在默认快捷键绑定 JSON 文件中找到（首选项：打开默认键盘快捷键(JSON)）：

{ 
    "key": "f5",  
    "command": "workbench.action.debug.start",
    "when": "debuggersAvailable && !inDebugMode" 
}

上述内置启动调试器命令的快键键是 F5，它仅仅在适当的调试器可用（上下文中的 debuggersAvailable 为 true 时）且编辑器不在调试模式中（上下文中的 inDebugMode 为 false 时）才会启动。

条件操作符

你可以使用下列条件操作符

键-值 when 子句操作符

when子句中可以使用键值对匹配操作符。表达式 key =~ value 会把右侧作为正则表达式来匹配左侧。比如配置 Docker 文件的菜单项，你可以使用：

"when": "resourceFilename =~ /docker/"

可用上下文变量

下面是一些when子句中可以使用的上下文变量，这些值最终会被解析为布尔值 true/false。

这个表并不包含所有值，你可以在键盘快键键编辑器（首选项:打开键盘快捷键）或者默认快捷键绑定 JSON 文件（首选项：打开默认键盘快捷键(JSON)）中找到所有上下文变量。

?> 注意：你可以使用config.前缀，使用任意用户或工作区设置中的值。

激活/聚焦视图或面板相关的上下文变量

你可以用 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 - 评论
• workbench.view.search - 搜索， 当 search.location 设置到 panel 时

如果你想要在特定视图或者面板聚焦时触发 when 子句，使用 sideBarFocus 或 panelFocus 与 activeViewlet 或 activiewFocus 进行组合。

比如，下列 when 子句只会在文件资源管理器聚焦时才会为真

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

在 when 子句中检查设置

在 when 子句中，你可以使用config.获取配置（设置）中的值。比如 config.editor.tabCompletion 或 config.breadcrumbs.enabled

添加自定义 when 子句上下文

如果你的插件需要使用 when 子句启动/禁用命令、菜单或者视图，而已有的上下文变量都不满足你的需求，你可以用 setContext 命令设置你自己的变量。

下面的第一个例子设置键myExtension:showMyCommand为真，你就可以在命令中或者 when 属性中进行使用了。第二个例子储存了一个值，那么你就可以在 when 子句中检查这个属性值是否大于 2 了。

vscode.commands.executeCommand('setContext', 'myExtension.showMyCommand', true);
vscode.commands.executeCommand('setContext', 'myExtension.numberOfCoolOpenThings', 4);

‘in’ 条件操作符

when中的操作符in 允许在上下文变量中动态查找其他的上下文变量值。比如，给包含特定文件的文件夹添加一个特殊的菜单命令（或者无法静态得知的其他东西），你可以使用 in 操作符来实现。

第一，确定需要支持的文件夹类型，比如是一个名称数组。然后，使用 setContext 命令把数组注入到上下文变量中：

vscode.commands.executeCommand('setContext', 'ext.supportedFolders', [
  'test',
  'foo',
  'bar'
]);
// 或者
// 注意本例（使用了一个对象）, 具体值是无关紧要的只要键存在于对象中
vscode.commands.executeCommand('setContext', 'ext.supportedFolders', {
  test: true,
  foo: 'anything',
  bar: false
});

然后在 package.json 中添加explorer/context菜单配置：

// 注意，本例假设你已经定义了一个叫做ext.doSpecial的命令
"menus": {
  "explorer/context": [
    {
      "command": "ext.doSpecial",
      "when": "explorerResourceIsFolder && resourceFilename in ext:supportedFolders"
    }
  ]
}

在这个例子里，我们拿到 resourceFilename 的值（在本例中也就是文件夹的名字）然后检查它是否在 ext:supportedFolders 之中。如果存在的话，菜单就会展示出来。这个强大的操作符使得更复杂的条件分支得以实现，同时也支持了动态配置。

查看上下文变量的工具

如果你想在运行时查看当前所有激活的上下文变量，你可以打开命令面板(⇧⌘P) 使用 开发人员:检查上下文键值 命令。这个命令会打开 VS Code 开发者工具的 Console 标签（或 帮助 > 打开开发者工具）然后显示出上下文变量的键值。

当你运行 开发人员:检查上下文键值，你的鼠标会高亮 VS Code UI 中的元素，当你点击一个元素时，对应的上下文变量和它们的状态就会输出到 Console 中。

一系列可能包含 自定义上下文变量 的键值对会展示出来。

!> 注意：部分 VS Code 内部使用的上下文变量在未来可能会有所变化。