mousetrap.js使用详解

I. Mousetrap.bind

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();
});

 

Mousetrap 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键的keydown侦听器，并且您按o上面序列的一部分，o则不会触发该事件。一旦序列被破坏，它将再次发射。

重要的是要注意，如果您有一个使用序列开头的相同键的单个键处理程序，Mousetrap会变得非常困惑。这是因为它无法判断您是否正在启动序列，或者您是否自己按下该键。

Shift键

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

 

需要的钥匙会shift为您神奇地处理。他们应该工作。对于keypress事件，他们将尝试匹配角色和for，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是一个被调用的方法，用于查看键盘事件是否应根据您是否在表单输入字段内触发。

它传递了三个参数：

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

如果返回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();

 

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

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

VI。Mousetrap.handleKey

Mousetrap.handleKey是每次按下键时调用的方法。如果您不知道自己在做什么，那么覆盖此函数真的不是一个好主意，但它允许您进行本机捕获无法实现的自定义处理。

它传递了三个参数：

• character - 按下的实际角色
• 修饰符 - 按下键时按住的修改器数组
• 触发此回调的电子密钥事件

包装特定元素

从版本开始1.5，可以将Mousetrap附加到页面上的特定元素。

默认情况下，所有绑定都应用于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表单内的文本区域，则回调仍将触发。

因此，当Mousetrap附加到特定元素时，关于未在textarea或输入内部触发的事件的默认规则不适用。

请注意，每个实例都会跟踪自己的回调，因此如果将相同的键绑定到多个元素，除非您使用，否则所有单个回调都将触发event.stopPropagation()。

七。Mousetrap.addKeycodes

此方法已在版本中添加1.6.0。它允许您将自定义键码添加到Mousetrap中的内部地图，而无需编辑库本身。

它接受一个参数。您应该传入一个包含映射到键名称的键代码的对象。

例如，如果要添加numlock键，则可以执行以下操作：

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

扩展捕鼠器

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

一些示例扩展是：

全局绑定

此扩展允许您指定可在任何位置工作的键盘事件，包括textarea / input字段内部。

(function(a){var c={},d=a.prototype.stopCallback;a.prototype.stopCallback=function(e,b,a,f){return this.paused?!0:c[a]||c[f]?!1:d.call(this,e,b,a)};a.prototype.bindGlobal=function(a,b,d){this.bind(a,b,d);if(a instanceof Array)for(b=0;b<a.length;b++)c[a[b]]=!0;else c[a]=!0};a.init()})(Mousetrap);

用法如下：

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

这意味着使用绑定的键盘事件Mousetrap.bind仅在表单输入字段之外工作，但使用Moustrap.bindGlobal将在两个地方都有效。

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

绑定字典

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

(function(b){var c=b.prototype.bind,a;b.prototype.bind=function(){a=arguments;if("string"==typeof a[0]||a[0]instanceof Array)return c.call(this,a[0],a[1],a[2]);for(var b in a[0])a[0].hasOwnProperty(b)&&c.call(this,b,a[0][b],a[1])};b.init()})(Mousetrap);

用法如下：

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

 

您可以选择传递keypress，keydown或keyup作为第二个参数。

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

暂停/取消暂停

此扩展允许暂停和取消暂停鼠标捕捉，而无需重置键盘快捷键并重新绑定它们。

(function(a){var b=a.prototype.stopCallback;a.prototype.stopCallback=function(a,c,d){return this.paused?!0:b.call(this,a,c,d)};a.prototype.pause=function(){this.paused=!0};a.prototype.unpause=function(){this.paused=!1};a.init()})(Mousetrap);

用法如下：

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

 

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

 

记录

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

(function(d){function n(b,a,h){if(this.recording)if("keydown"==h.type){1===b.length&&g&&k();for(i=0;i<a.length;++i)l(a[i]);l(b)}else"keyup"==h.type&&0<c.length&&k();else p.apply(this,arguments)}function l(b){var a;for(a=0;a<c.length;++a)if(c[a]===b)return;c.push(b);1===b.length&&(g=!0)}function k(){e.push(c);c=[];g=!1;clearTimeout(m);m=setTimeout(q,1E3)}function r(b){var a;for(a=0;a<b.length;++a)b[a].sort(function(a,b){return 1<a.length&&1===b.length?-1:1===a.length&&1<b.length?1:a>b?1:-1}),b[a]=
b[a].join("+")}function q(){f&&(r(e),f(e));e=[];f=null;c=[]}var e=[],f=null,c=[],g=!1,m=null,p=d.prototype.handleKey;d.prototype.record=function(b){var a=this;a.recording=!0;f=function(){a.recording=!1;b.apply(a,arguments)}};d.prototype.handleKey=function(){n.apply(this,arguments)};d.init()})(Mousetrap);

用法如下：

<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>

 

使用扩展

要使用这些扩展中的任何一个，您只需在包含Mousetrap后在页面上包含javascript即可。