快捷键与键绑定

快捷键是插件易用性的关键。contributes.keybindings 声明默认键位，when 条件控制生效场景，用户可用 keybindings.json 自由覆盖。

注册快捷键

package.json 中声明：

{
  "contributes": {
    "keybindings": [
      {
        "command": "mylinter.run",
        "key": "ctrl+shift+m",
        "when": "editorTextFocus"
      },
      {
        "command": "mylinter.fixAll",
        "key": "ctrl+shift+alt+m",
        "mac": "cmd+shift+alt+m",
        "when": "editorTextFocus && !editorReadonly"
      }
    ]
  }
}

字段说明

字段	说明
command	绑定的命令 ID
key	默认键位（跨平台）
mac	macOS 专用键位（覆盖 key）
linux	Linux 专用键位
win	Windows 专用键位
when	生效条件表达式

key 键位语法

键位由修饰键 + 主键组成：

修饰键	表示
Ctrl	ctrl
Shift	shift
Alt	alt
Meta/Command	meta（macOS 为 Cmd）

{
  "command": "mylinter.run",
  "key": "ctrl+shift+alt+m",
  "mac": "cmd+shift+alt+m"
}

常用主键

类型	示例
字母	a、b、m
数字	0、1、9
功能键	f1、f5、f12
方向键	up、down、left、right
特殊键	space、enter、tab、backspace、escape
标点	+、-、=、[、]、\、;、,、.、/
鼠标	button1、button2（支持鼠标键）

组合键示例

{
  "command": "mylinter.nextProblem",
  "key": "f8",
  "when": "editorTextFocus"
},
{
  "command": "mylinter.prevProblem",
  "key": "shift+f8",
  "when": "editorTextFocus"
},
{
  "command": "mylinter.openPanel",
  "key": "ctrl+alt+m",
  "mac": "cmd+alt+m",
  "when": "!editorIsOpen"
}

连击键（Chord）

用空格连接两个键位形成连击：

{
  "command": "mylinter.showRuleDoc",
  "key": "ctrl+k ctrl+m"
}

按 ctrl+k 再按 ctrl+m 触发。连击键是二级快捷键的惯例做法。

when 条件表达式

when 控制键位何时生效，用 &&、||、! 组合上下文变量：

{
  "command": "mylinter.run",
  "key": "ctrl+shift+m",
  "when": "editorTextFocus && !editorReadonly && !inDebugMode"
}

常用上下文变量

变量	含义
editorTextFocus	编辑器有焦点
editorFocus	编辑器聚焦（含内嵌）
editorReadonly	编辑器只读
editorIsOpen	有打开的编辑器
inDebugMode	处于调试模式
resourceLangId	当前文件语言 ID
resourceFilename	当前文件名
resourceScheme	资源协议（file/untitled）
resourceExtname	文件扩展名
terminalFocus	终端聚焦
sideBarVisible	侧边栏可见
explorerResourceIsFolder	资源管理器选中文件夹
view	当前视图 ID
scmProvider	当前 SCM 提供者
config.xxx	配置值

语言限定

{
  "command": "mylinter.run",
  "key": "ctrl+shift+m",
  "when": "editorTextFocus && resourceLangId == javascript"
}

resourceLangId == javascript 让快捷键仅在 JS 文件中生效。

组合条件

{
  "command": "mylinter.run",
  "key": "ctrl+shift+m",
  "when": "editorTextFocus && resourceLangId != markdown"
},
{
  "command": "mylinter.run",
  "key": "ctrl+shift+m",
  "when": "terminalFocus || editorTextFocus"
}

自定义上下文

插件用 setContext 定义自己的上下文变量：

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // 设置自定义上下文
  vscode.commands.executeCommand(
    'setContext',
    'mylinter.enabled',
    true
  );

  // 根据配置/状态动态更新
  const update = () => {
    const enabled = vscode.workspace
      .getConfiguration('mylinter')
      .get<boolean>('enable', true);
    vscode.commands.executeCommand('setContext', 'mylinter.enabled', enabled);
  };
  update();
}

{
  "contributes": {
    "keybindings": [
      {
        "command": "mylinter.run",
        "key": "ctrl+shift+m",
        "when": "editorTextFocus && mylinter.enabled"
      }
    ]
  }
}

冲突检测

键位冲突时，VS Code 在"键盘快捷方式"编辑器标红提示：

键盘快捷方式（Ctrl+K Ctrl+S）
 └─ 搜索 mylinter.run
    └─ 如果有冲突键位显示 ⚠

开发时检查冲突的方法：

命令面板 → Preferences: Keyboard Shortcuts
  → 查看冲突提示

keybindings.json 用户覆盖

用户可以覆盖插件的默认键位：

{
  "keybindings": [
    {
      "command": "mylinter.run",
      "key": "ctrl+r ctrl+m",
      "when": "editorTextFocus"
    }
  ]
}

用户覆盖优先级高于插件默认。插件作者应选择较少冲突的默认键位，避免占用常用组合。

移除插件默认键位

{
  "keybindings": [
    {
      "command": "-mylinter.run",
      "key": "ctrl+shift+m"
    }
  ]
}

命令前加 - 移除默认绑定。

组合命令

runCommands 支持一次触发多个命令：

vscode.commands.registerCommand('mylinter.run', () => {
  vscode.commands.executeCommand('runCommands', {
    commands: [
      { command: 'editor.action.formatDocument' },
      { command: 'mylinter.collectDiagnostics' }
    ]
  });
});

完整示例

{
  "contributes": {
    "keybindings": [
      {
        "command": "mylinter.run",
        "key": "ctrl+shift+m",
        "mac": "cmd+shift+m",
        "when": "editorTextFocus && !editorReadonly"
      },
      {
        "command": "mylinter.fixAll",
        "key": "ctrl+shift+alt+m",
        "mac": "cmd+shift+alt+m",
        "when": "editorTextFocus && !editorReadonly && !inDebugMode"
      },
      {
        "command": "mylinter.nextProblem",
        "key": "f8",
        "when": "editorTextFocus"
      },
      {
        "command": "mylinter.prevProblem",
        "key": "shift+f8",
        "when": "editorTextFocus"
      }
    ],
    "menus": {
      "commandPalette": [
        {
          "command": "mylinter.run",
          "when": "mylinter.enabled"
        }
      ]
    }
  }
}

快捷键测试清单

检查	方法
平台差异	分别测试 Windows/macOS/Linux
when 条件	编辑器焦点/只读/语言/调试模式
冲突	键盘快捷方式编辑器检查
连击键	按两段验证时序
菜单联动	命令面板过滤条件生效

快捷键、配置、本地化构成插件体验的三件套。最后一篇实战把配置驱动能力组装成可用的代码检查插件。