快捷键

<!--分割线-->

HotKeys.js 是一个具有一些特殊功能的输入捕获库，易于上手和使用，体积合理（~6kB）（gzip压缩后：2.8kB），且没有依赖。它不应该干扰任何JavaScript库或框架。官方文档演示预览。更多示例。

╭┈┈╮          ╭┈┈╮  ╭┈┈╮
┆  ├┈┈..┈┈┈┈┈.┆  └┈╮┆  ├┈┈..┈┈┈┈┈..┈┈.┈┈..┈┈┈┈┈.
┆     ┆┆  □  ┆┆   ┈┤┆    < ┆  -__┘┆  ┆  ┆┆__ ┈┈┤
╰┈┈┴┈┈╯╰┈┈┈┈┈╯╰┈┈┈┈╯╰┈┈┴┈┈╯╰┈┈┈┈┈╯╰┈┈┈  ┆╰┈┈┈┈┈╯
                                  ╰┈┈┈┈┈╯

使用方法

你需要在系统上安装 Node.js。

npm install hotkeys-js --save

import hotkeys from 'hotkeys-js';

hotkeys('f5', function(event, handler){
  // 阻止 WINDOWS 系统下的默认刷新事件
  event.preventDefault()
  alert('你按下了 F5!')
});

或者手动下载并在你的 HTML 中链接 hotkeys.js，也可以通过 UNPKG 下载：

CDN：UNPKG | jsDelivr | Githack | Statically | bundle.run

<script src="https://unpkg.com/hotkeys-js/dist/hotkeys.min.js"></script>
<script type="text/javascript">
hotkeys('ctrl+a,ctrl+b,r,f', function (event, handler){
  switch (handler.key) {
    case 'ctrl+a': alert('你按下了 ctrl+a!');
      break;
    case 'ctrl+b': alert('你按下了 ctrl+b!');
      break;
    case 'r': alert('你按下了 r!');
      break;
    case 'f': alert('你按下了 f!');
      break;
    default: alert(event);
  }
});
</script>

在 React 中使用

react-hotkeys 是一个监听键盘按下和释放事件的 React 组件，用于定义和分发键盘快捷键。详细使用方法请参见其文档 react-hotkeys。

react-hotkeys-hook - 用于在组件中使用键盘快捷键的 React 钩子。请确保你安装的 react 和 react-dom 版本至少为 16.8，否则钩子将无法工作。

浏览器支持

Hotkeys.js 已经经过测试，应该可以在以下浏览器中工作。

Internet Explorer 6+
Safari
Firefox
Chrome

支持的按键

HotKeys 支持以下修饰键：⇧、shift、option、⌥、alt、ctrl、control、command 和 ⌘。

以下特殊键可用于快捷键：backspace、tab、clear、enter、return、esc、escape、space、up、down、left、right、home、end、pageup、pagedown、del、delete、f1 到 f19、num_0 到 num_9、num_multiply、num_add、num_enter、num_subtract、num_decimal、num_divide。

⌘ Command() ⌃ Control ⌥ Option(alt) ⇧ Shift ⇪ Caps Lock(Capital) fn 不支持 fn ↩︎ return/Enter space

定义快捷键

暴露了一个全局方法 key，直接调用即可定义快捷键。

hotkeys([keys:<String>], [option:[string|object|function]], [callback:<function>])

hotkeys('f5', function(event, handler) {
  // 阻止 WINDOWS 系统下的默认刷新事件
  event.preventDefault();
  alert('你按下了 F5!');
});

// 返回 false 可以阻止事件并防止默认浏览器事件
// Mac OS 系统将 `command + r` 定义为刷新快捷键
hotkeys('ctrl+r, command+r', function() {
  alert('停止刷新!');
  return false;
});

// 单个按键
hotkeys('a', function(event,handler){
  //event.srcElement: input
  //event.target: input
  if(event.target === "input"){
      alert('你按下了 a!')
  }
  alert('你按下了 a!')
});

// 组合键
hotkeys('ctrl+a,ctrl+b,r,f', function (event, handler){
  switch (handler.key) {
    case 'ctrl+a': alert('你按下了 ctrl+a!');
      break;
    case 'ctrl+b': alert('你按下了 ctrl+b!');
      break;
    case 'r': alert('你按下了 r!');
      break;
    case 'f': alert('你按下了 f!');
      break;
    default: alert(event);
  }
});

hotkeys('ctrl+a+s', function() {
    alert('你按下了 ctrl+a+s!');
});

// 使用作用域
hotkeys('*','wcj', function(event){
  console.log('做些事情', event);
});

选项

• scope<String>
• element<HTMLElement>
• keyup<Boolean>
• keydown<Boolean>
• splitKey<string> (默认为 +)
• capture<Boolean>
• single<Boolean>

hotkeys('o, enter', {
  scope: 'wcj',
  element: document.getElementById('wrapper'),
}, function() {
  console.log('做些其他事情');
});

hotkeys('ctrl-+', { splitKey: '-' }, function(e) {
  console.log('你按下了 ctrl 和 +');
});

hotkeys('+', { splitKey: '-' }, function(e){
  console.log('你按下了 +');
})

keyup

按键按下和按键释放都执行回调事件。

hotkeys('ctrl+a,alt+a+s', {keyup: true}, function(event, handler) {
  if (event.type === 'keydown') {
    console.log('keydown:', event.type, handler, handler.key);
  }

  if (event.type === 'keyup') {
    console.log('keyup:', event.type, handler, handler.key);
  }
});

API 参考

星号 "*"

修饰键判断

hotkeys('*', function() {
  if (hotkeys.shift) {
    console.log('shift 被按下!');
  }

  if (hotkeys.ctrl) {
    console.log('ctrl 被按下!');
  }

  if (hotkeys.alt) {
    console.log('alt 被按下!');
  }

  if (hotkeys.option) {
    console.log('option 被按下!');
  }

  if (hotkeys.control) {
    console.log('control 被按下!');
  }

  if (hotkeys.cmd) {
    console.log('cmd 被按下!');
  }

  if (hotkeys.command) {
    console.log('command 被按下!');
  }
});

setScope

使用 hotkeys.setScope 方法设置作用域。除了 'all' 之外，只能有一个活动作用域。默认情况下，'all' 始终处于活动状态。

// 使用作用域定义快捷键
hotkeys('ctrl+o, ctrl+alt+enter', 'issues', function() {
  console.log('做些事情');
});
hotkeys('o, enter', 'files', function() {
  console.log('做些其他事情');
});

// 设置作用域（只有 'all' 和 'issues' 的快捷键会生效）
hotkeys.setScope('issues'); // 默认作用域是 'all'

getScope

使用 hotkeys.getScope 方法获取作用域。

hotkeys.getScope();

deleteScope

使用 hotkeys.deleteScope 方法删除作用域。这也会删除与之关联的所有热键。

hotkeys.deleteScope('issues');

如果需要在删除后设置新的作用域，可以使用第二个参数。

hotkeys.deleteScope('issues', 'newScopeName');

unbind

与定义快捷键类似，可以使用 hotkeys.unbind 解绑快捷键。

// 解绑 'a' 的处理程序
hotkeys.unbind('a');

// 仅为单个作用域解绑热键
// 如果未指定作用域，默认为当前作用域 (hotkeys.getScope())
hotkeys.unbind('o, enter', 'issues');
hotkeys.unbind('o, enter', 'files');

通过函数解绑事件。

function example() {
  hotkeys('a', example);
  hotkeys.unbind('a', example);

  hotkeys('a', 'issues', example);
  hotkeys.unbind('a', 'issues', example);
}

解绑所有内容。

hotkeys.unbind();

isPressed

例如，如果当前按下 M 键，则 hotkeys.isPressed(77) 为 true。

hotkeys('a', function() {
  console.log(hotkeys.isPressed('a')); //=> true
  console.log(hotkeys.isPressed('A')); //=> true
  console.log(hotkeys.isPressed(65)); //=> true
});

trigger

触发快捷键事件

hotkeys.trigger('ctrl+o');
hotkeys.trigger('ctrl+o', 'scope2');

getPressedKeyCodes

返回当前按下的键码数组。

hotkeys('command+ctrl+shift+a,f', function() {
  console.log(hotkeys.getPressedKeyCodes()); //=> [17, 65] 或 [70]
})

getPressedKeyString

返回当前按下的键码数组。

hotkeys('command+ctrl+shift+a,f', function() {
  console.log(hotkeys.getPressedKeyString()); //=> ['⌘', '⌃', '⇧', 'A', 'F']
})

getAllKeyCodes

获取所有注册的键码列表。

hotkeys('command+ctrl+shift+a,f', function() {
  console.log(hotkeys.getAllKeyCodes());
  // [
  //   { scope: 'all', shortcut: 'command+ctrl+shift+a', mods: [91, 17, 16], keys: [91, 17, 16, 65] },
  //   { scope: 'all', shortcut: 'f', mods: [], keys: [42] }
  // ]
})

filter

默认情况下，热键在 INPUT、SELECT、TEXTAREA 元素中不会启用。Hotkeys.filter 返回 true 时快捷键设置生效，返回 false 时快捷键设置失效。

hotkeys.filter = function(event){
  return true;
}
// 如何为可编辑标签添加过滤器。<div contentEditable="true"></div>
// "contentEditable" 不支持的旧浏览器会忽略
hotkeys.filter = function(event) {
  var target = event.target || event.srcElement;
  var tagName = target.tagName;
  return !(target.isContentEditable || tagName == 'INPUT' || tagName == 'SELECT' || tagName == 'TEXTAREA');
}

hotkeys.filter = function(event){
  var tagName = (event.target || event.srcElement).tagName;
  hotkeys.setScope(/^(INPUT|TEXTAREA|SELECT)$/.test(tagName) ? 'input' : 'other');
  return true;
}

noConflict

放弃 HotKeys 对 hotkeys 变量的控制。

var k = hotkeys.noConflict();
k('a', function() {
  console.log("do something")
});

hotkeys()
// -->Uncaught TypeError: hotkeys is not a function(anonymous function)
// @ VM2170:2InjectedScript._evaluateOn
// @ VM2165:883InjectedScript._evaluateAndWrap
// @ VM2165:816InjectedScript.evaluate @ VM2165:682

开发

要进行开发，请安装依赖并获取代码：

$ git https://github.com/jaywcjlove/hotkeys.git
$ cd hotkeys     # 进入目录
$ npm install    # 或  yarn install

要进行开发，运行自动重载的构建：

$ npm run watch

运行文档网站环境。

$ npm run doc

要贡献，请 fork Hotkeys.js，添加您的补丁和相应的测试（在 test/ 文件夹中），然后提交一个拉取请求。

$ npm run test
$ npm run test:watch # 开发模式

贡献者

一如既往，感谢我们了不起的贡献者！

<a href="https://github.com/jaywcjlove/hotkeys-js/graphs/contributors"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/1b29fb4b-96d5-40c8-98db-6242eeb1b50f.svg" /> </a>

使用 github-action-contributors 制作。

许可证

MIT © Kenny Wong