Mousetrap 超简单的处理键盘快捷键 JavaScript 库

Question

Mousetrap 是一个超简单的处理键盘快捷键的类库，压缩有只有 1.6kb 大小，并且不依赖任何的外部类库。

你使用的主要就是绑定方法，它会帮助你绑定指定的键盘命令到一个 callback 方法中。并且拥有第三个参数来制定监听的事件类型。

可以是 keypress，keydown 或者 keyup。任何被空格分隔的 key 会被认为是连续的。如果你你连续的输入 key，最后一个输入 key 会触发 callback。

开始使用

在关闭前在页面上包含 Mousetrap </body>标签

<script src="/path/to/mousetrap.min.js"></script>

或安装 mousetrap 从 npm 并要求

var Mousetrap = require( 'mousetrap ');

添加一些要侦听的键盘事件

// single keys
Mousetrap.bind('4', function() { console.log('4'); });
Mousetrap.bind("?", function() { console.log('show shortcuts!'); });
Mousetrap.bind('esc', function() { console.log('escape'); }, 'keyup');

// combinations
Mousetrap.bind('command+shift+k', function() { console.log('command shift k'); });

// map multiple combinations to the same callback
Mousetrap.bind(['command+k', 'ctrl+k'], function() {
  console.log('command k or control k');

  // return false to prevent default browser behavior
  // and stop event from bubbling
  return false;
});

// gmail style sequences
Mousetrap.bind('g i', function() { console.log('go to inbox'); });
Mousetrap.bind('* a', function() { console.log('select all'); });

// konami code!
Mousetrap.bind('up up down down left right left right b a enter', function() {
  console.log('konami code');
});

为什么使用 Mousetrap？

有许多其他类似的库存在，那么是什么使这个不同呢？

• 不存在外部依赖关系，不需要框架。
• 你不仅限于 keydown 事件(您可以指定 keypress, keydown，或keyup或者让老鼠陷阱为你选择)。
• 可以将键事件直接绑定到特殊键，例如?或*而不必指定shift+/或shift+8并不是所有的键盘都是一致的
• 它适用于国际键盘布局。
• 除了常规键和键组合之外，还可以绑定类似Gmail的密钥序列。
• 控件以编程方式触发关键事件。trigger()方法
• 它适用于键盘上的数字键盘。
• 代码有很好的文档/注释。

浏览器支持

Mousetrap 已经过测试，应该在：

• Internet Explorer 6+
• Safari
• Firefox
• Chrome

支撑键

对于可以使用的修饰符键 shift, ctrl, alt，或meta。

你可以代替 option 为 alt 和 command 为 meta。

其他特殊的钥匙是 backspace, tab, enter, return, capslock, esc, escape, space, pageup, pagedown, end, home, left, up, right, down, ins, del，和plus。

您应该能够按名称引用的任何其他键，如 a, /, $, * 或 =。

API参考

I. Mousetrap.bind

绑定方法是您将进行的主要调用。这将将指定的键盘命令绑定到回调方法。

单键

Mousetrap.bind('/', _focusSearch);

还有第三个参数可以用来指定要侦听的事件类型。可能是keypress, keydown或keyup.

如果你不确定，建议你不要讨论这个论点。鼠标陷阱将查看您正在绑定的键，并确定它是否应该默认为keypress或keydown.

键组合

Mousetrap.bind('ctrl+s', function(e) {
  _saveDraft();
});

如果要将多个键命令绑定到同一个回调，可以为第一个参数传入一个数组：

Mousetrap.bind(['ctrl+s', 'command+s'], function(e) {
  _saveDraft();
});

鼠夹1.4介绍了一个通用的mod帮助您设置跨平台快捷方式。

Mousetrap.bind('mod+s', _saveDraft);

在mac上，这最终会映射到command+s而在Windows和Linux上，它映射到ctrl+s.

这与上面的数组示例不同，因为两者都存在。ctrl+s和command+s将触发Mac上的保存，而使用mod只限于帮手command+s将要。

键序

Mousetrap.bind('* a', _selectAll, 'keydown');

这个特性是受Gmail启发的。由空格分隔的任何键都将被视为序列。如果您按顺序键入每个键，则序列中的最后一个键将触发回调。如果在序列中键入键或等待太久，则序列将重置。

您还可以创建一个序列，其中包含键组合。

Mousetrap.bind('g o command+enter', function() { /* do something */ });

如果在序列的上下文中按下键，通常会触发序列中的键的任何键事件都不会触发。

例如，如果您有一个用于o你按下键o作为上述序列的一部分，o靠自己不会开火。一旦序列被打破，它就会再次开火。

需要注意的是，如果您有一个使用与序列开头相同的键的单键处理程序，MouseTRAP可能会变得非常混乱。这是因为它无法判断您是在启动序列，还是自己按下了该键。

移位键

Mousetrap.bind('?', function() { alert('keyboard shortcuts'); });

需要的钥匙shift为你神奇地处理。他们应该工作。带着keypress事件，他们将试图匹配字符和keyup和keydown有一个映射，允许他们工作。

请注意keypress是非美国键盘最可靠的

文本字段

默认情况下，所有键盘事件将不如果你在一个textarea, input，或select防止不受欢迎的事情发生。

如果你想让他们开火，你可以添加这个类。mousetrap元素。

<textarea name="message" class="mousetrap"></textarea>

您还可以通过覆盖来自定义此功能。Mousetrap.stopCallback。见下文

覆盖特定事件

如果以后在脚本中绑定相同的键事件，它应该会覆盖您指定的原始回调。

从回调检查键盘组合

截至版本1.2回调将通过触发事件的键盘组合字符串传递第二个参数。

Mousetrap.bind('ctrl+shift+up', function(e, combo) {
  console.log(combo); // logs 'ctrl+shift+up'
});

这个例子有点做作，因为你显然知道捷径。但是，如果您想要对一组组合使用相同的回调函数，然后检查哪个回调函数触发了允许您这样做的事件。

停止默认行为

这通常不是一个好做法，但有时您可能希望覆盖浏览器中键盘组合的默认行为。

例如，假设您希望在不键入该键的情况下聚焦表单输入，或者您有希望在用户按下时保存的文本输入。ctrl+s。你有几种方法可以做到这一点。

可以显式防止默认行为：

Mousetrap.bind(['ctrl+s', 'meta+s'], function(e) {
  if (e.preventDefault) {
    e.preventDefault();
  } else {
    // internet explorer
    e.returnValue = false;
  }
  _saveDraft();
});

您可以在这里看到回调函数被传递到触发它的原始键事件。

为了方便起见，您还可以在回调中返回false：

Mousetrap.bind(['ctrl+s', 'meta+s'], function(e) {
  _saveDraft();
  return false;
});

回归false这里的工作方式与jQuery的相同return false。它防止默认操作，并阻止事件冒泡。

II. Mousetrap.unbind

Mousetrap.unbind('?');

此方法将解除单个键盘事件或键盘事件数组的绑定。您应该将密钥组合传递到与最初传入的完全相同的位置。bind.

如果你当初打电话给mousetrap.bind并以类似的类型传递keyup或keydown作为第二个参数，您也必须将其传递给unbind调用。

Mousetrap.unbind('a', 'keyup');

III. Mousetrap.trigger

Mousetrap.trigger('esc');

任何已绑定的键盘事件都可以通过传入最初绑定时使用的字符串来触发。

请注意，这实际上并不会触发浏览器中的关键事件。它只是简单地触发了绑定到捕鼠器中的键的事件。

此方法还接受要触发的事件类型的可选参数。

IV. Mousetrap.stopCallback

Mousetrap.stopCallback 是一种方法，用于查看键盘事件是否应该根据窗体输入字段中的情况触发。

它被传递了三个参数：

• 触发此回调的电子密钥事件。
• 元素-引用事件的目标元素。
• 组合键-触发事件的特定键盘组合

如果返回true，则会阻止回调触发，如果为false，则会触发回调。

默认实现是：

stopCallback: function(e, element, combo) {

  // if the element has the class "mousetrap" then no need to stop
  if ((' ' + element.className + ' ').indexOf(' mousetrap ') > -1) {
    return false;
  }

  // stop for input, select, and textarea
  return element.tagName == 'INPUT' || element.tagName == 'SELECT' || element.tagName == 'TEXTAREA' || (element.contentEditable && element.contentEditable == 'true');
}

V. Mousetrap.reset

Mousetrap.reset();

重置方法将删除与捕鼠器绑定的任何内容。如果您想在不刷新浏览器页面的情况下更改应用程序中的上下文，这将非常有用。您可以在新页面中使用Ajax，调用Reset，然后绑定该页面所需的关键事件。

在内部，捕鼠器保留要侦听的所有事件的关联数组，因此重置不会实际删除或添加文档中的事件侦听器。它只是将数组设置为空。

VI. Mousetrap.handleKey

Mousetrap.handleKey 是每次按下键时都会调用的方法。如果您不知道您在做什么，那么重写这个函数确实不是一个好主意，但是它允许您进行自定义处理，而这些操作在捕鼠器中是不可能的。

它被传递了三个参数：

• 字符-按下的实际字符
• 修饰符-按下键时按下的修饰符数组。
• 触发此回调的电子密钥事件。

包裹特定元素

截至版本1.5可以将鼠标夹附加到页面上的特定元素。

默认情况下，所有绑定都应用于 document 但是，如果您有一个要向其应用特定事件的表单，则可以这样做：

var form = document.querySelector('form');
Mousetrap(form).bind('mod+s', function(e, combo) {
  // save the form
});

如果要将一堆东西绑定到相同的元素，还可以创建一个新的MouseTRAP实例。

var form = document.querySelector('form');
var mousetrap = new Mousetrap(form);
mousetrap.bind('mod+s', _handleSave);
mousetrap.bind('mod+z', _handleUndo);

从您绑定的元素的子元素触发的任何事件都会冒泡。这意味着在上面的例子中，如果您按下command+s在表单中的文本区域中，回调仍然会触发。

因此，关于未在文本区域或输入中触发的事件的默认规则可以执行。不当鼠标夹连接到特定的元素时应用。

请注意，每个实例都跟踪自己的回调，因此如果将相同的键绑定到多个元素，那么除非使用event.stopPropagation().

VII. Mousetrap.addKeycodes

此方法是在版本中添加的。1.6.0。它允许您将自定义密钥代码添加到MouseTRAP的内部映射中，而无需编辑库本身。

它只接受一个论点。您应该传入一个包含映射到密钥名的密钥代码的对象。

例如，如果要添加NumLock键，可以这样做：

Mousetrap.addKeycodes({
  144: 'numlock'
});

扩展 Mousetrap

任何公共方法都可以被覆盖以扩展 Mousetrap。

几个示例扩展如下：

全局绑定

View or Download

此扩展允许您指定将在任何地方工作的键盘事件，包括在TextArea/Input字段中。

用法如下：

Mousetrap.bindGlobal('ctrl+s', function() {
  _save();
});

这意味着键盘事件绑定使用Mousetrap.bind将只在窗体输入字段之外工作，但使用Moustrap.bindGlobal在两个地方都能工作。

如果您想要创建仅在特定文本区域中工作的键盘快捷键，您也可以通过创建自己的扩展来实现这一点。

绑定字典

View or Download

此扩展覆盖默认绑定行为，并允许您在单个绑定调用中绑定多个组合。

用法如下：

Mousetrap.bind({
  'a': function() { console.log('a'); },
  'b': function() { console.log('b'); }
});

你可以随意进入keypress, keydown或keyup作为第二个论点。

其他绑定调用的工作方式与默认情况相同。

暂停/取消暂停

View or Download

此扩展允许鼠标陷阱暂停和取消暂停，而不必重置键盘快捷键并重新绑定它们。

用法如下：

// stop Mousetrap events from firing
Mousetrap.pause();

// allow Mousetrap events to fire again
Mousetrap.unpause();

记录

View or Download

此扩展允许您从应用程序中记录键盘快捷键。例如，如果您想让用户为在您的页面上执行操作指定自己的键盘快捷键，您可以要求他们输入快捷方式。

用法如下：

<button onclick="recordSequence()">Record</button>

<script>
  function recordSequence() {
    Mousetrap.record(function(sequence) {
      // sequence is an array like ['ctrl+k', 'c']
      alert('You pressed: ' + sequence.join(' '));
    });
  }
</script>

使用扩展

要使用这些扩展中的任何一个，只需将 JavaScript 文件包含在页面中，然后包含 Mousetrap。

相关链接

• 官网：https://craig.is/killing/mice
• Github 地址：https://github.com/ccampbell/mousetrap