1 | # Hotkeys
|
2 |
|
3 |
|
4 |
|
5 | [![](https://img.shields.io/github/issues/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/issues) [![](https://img.shields.io/github/forks/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/network) [![](https://img.shields.io/github/stars/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/stargazers) [![](https://img.shields.io/github/release/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/releases) ![](http://jaywcjlove.github.io/sb/status/no-dependencies.svg) [![Build Status](https://www.travis-ci.org/jaywcjlove/hotkeys.svg?branch=master)](https://www.travis-ci.org/jaywcjlove/hotkeys) [![Coverage Status](https://coveralls.io/repos/github/jaywcjlove/hotkeys/badge.svg?branch=master)](https://coveralls.io/github/jaywcjlove/hotkeys?branch=master) [![jaywcjlove/hotkeys](https://jaywcjlove.github.io/sb/lang/chinese.svg)](./README-zh.md) [![jaywcjlove/hotkeys](https://jaywcjlove.github.io/sb/ico/gitee.svg)](https://gitee.com/jaywcjlove/hotkeys)
|
6 |
|
7 | HotKeys.js is an input capture library with some very special features, it is easy to pick up and use, has a reasonable footprint ([~3kb](https://bundlephobia.com/result?p=hotkeys-js)) (gzipped: 1.73kb), and has no dependencies. It should not interfere with any JavaScript libraries or frameworks. Official document [demo preview](http://jaywcjlove.github.io/hotkeys). [More examples](https://github.com/jaywcjlove/hotkeys/issues?q=label%3ADemo+).
|
8 |
|
9 | ```bash
|
10 | ╭┈┈╮ ╭┈┈╮ ╭┈┈╮
|
11 | ┆ ├┈┈..┈┈┈┈┈.┆ └┈╮┆ ├┈┈..┈┈┈┈┈..┈┈.┈┈..┈┈┈┈┈.
|
12 | ┆ ┆┆ □ ┆┆ ┈┤┆ < ┆ -__┘┆ ┆ ┆┆__ ┈┈┤
|
13 | ╰┈┈┴┈┈╯╰┈┈┈┈┈╯╰┈┈┈┈╯╰┈┈┴┈┈╯╰┈┈┈┈┈╯╰┈┈┈ ┆╰┈┈┈┈┈╯
|
14 | ╰┈┈┈┈┈╯
|
15 | ```
|
16 |
|
17 | ## Usage
|
18 |
|
19 | You will need `Node.js` installed on your system.
|
20 |
|
21 | ```bash
|
22 | $ npm install hotkeys-js --save
|
23 | ```
|
24 |
|
25 | ```js
|
26 | import hotkeys from 'hotkeys-js';
|
27 |
|
28 | hotkeys('f5', function(event, handler){
|
29 | // Prevent the default refresh event under WINDOWS system
|
30 | event.preventDefault()
|
31 | alert('you pressed F5!')
|
32 | });
|
33 | ```
|
34 |
|
35 | Or manually download and link **hotkeys.js** in your HTML, It can also be downloaded via [UNPKG](https://unpkg.com/hotkeys-js/dist/):
|
36 |
|
37 | CDN: [UNPKG](https://unpkg.com/hotkeys-js/dist/) | [jsDelivr](https://cdn.jsdelivr.net/npm/hotkeys-js@3.7.3/) | [Githack](https://raw.githack.com/jaywcjlove/hotkeys/master/dist/hotkeys.min.js) | [Statically](https://cdn.statically.io/gh/jaywcjlove/hotkeys/master/dist/hotkeys.min.js) | [bundle.run](https://bundle.run/hotkeys-js@3.7.3)
|
38 |
|
39 | ```html
|
40 | <script src="https://unpkg.com/hotkeys-js/dist/hotkeys.min.js"></script>
|
41 | <script type="text/javascript">
|
42 | hotkeys('ctrl+a,ctrl+b,r,f', function (event, handler){
|
43 | switch (handler.key) {
|
44 | case 'ctrl+a': alert('you pressed ctrl+a!');
|
45 | break;
|
46 | case 'ctrl+b': alert('you pressed ctrl+b!');
|
47 | break;
|
48 | case 'r': alert('you pressed r!');
|
49 | break;
|
50 | case 'f': alert('you pressed f!');
|
51 | break;
|
52 | default: alert(event);
|
53 | }
|
54 | });
|
55 | </script>
|
56 | ```
|
57 |
|
58 | ### Used in React
|
59 |
|
60 | [react-hotkeys](https://github.com/jaywcjlove/react-hotkeys) is the React component that listen to keydown and keyup keyboard events, defining and dispatching keyboard shortcuts. Detailed use method please see its documentation [react-hotkeys](https://github.com/jaywcjlove/react-hotkeys).
|
61 |
|
62 | [react-hotkeys-hook](https://github.com/JohannesKlauss/react-hotkeys-hook) - React hook for using keyboard shortcuts in components. Make sure that you have at least version 16.8 of react and react-dom installed, or otherwise hooks won't work for you.
|
63 |
|
64 | ## Browser Support
|
65 |
|
66 | Hotkeys.js has been tested and should work in.
|
67 |
|
68 | ```shell
|
69 | Internet Explorer 6+
|
70 | Safari
|
71 | Firefox
|
72 | Chrome
|
73 | ```
|
74 |
|
75 | ## Supported Keys
|
76 |
|
77 | HotKeys understands the following modifiers: `⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, and `⌘`.
|
78 |
|
79 | The following special keys can be used for shortcuts: backspace, tab, clear, enter, return, esc, escape, space, up, down, left, right, home, end, pageup, pagedown, del, delete and f1 through f19.
|
80 |
|
81 | `⌘` Command()
|
82 | `⌃` Control
|
83 | `⌥` Option(alt)
|
84 | `⇧` Shift
|
85 | `⇪` Caps Lock(Capital)
|
86 | ~~`fn` Does not support fn~~
|
87 | `↩︎` return/Enter space
|
88 |
|
89 | ## Defining Shortcuts
|
90 |
|
91 | One global method is exposed, key which defines shortcuts when called directly.
|
92 |
|
93 | ```js
|
94 | hotkeys([keys:<String>], [option:[string|object|function]], [callback:<function>])
|
95 | ```
|
96 |
|
97 |
|
98 | ```js
|
99 | hotkeys('f5', function(event, handler) {
|
100 | // Prevent the default refresh event under WINDOWS system
|
101 | event.preventDefault();
|
102 | alert('you pressed F5!');
|
103 | });
|
104 |
|
105 | // Returning false stops the event and prevents default browser events
|
106 | // Mac OS system defines `command + r` as a refresh shortcut
|
107 | hotkeys('ctrl+r, command+r', function() {
|
108 | alert('stopped reload!');
|
109 | return false;
|
110 | });
|
111 |
|
112 | // Single key
|
113 | hotkeys('a', function(event,handler){
|
114 | //event.srcElement: input
|
115 | //event.target: input
|
116 | if(event.target === "input"){
|
117 | alert('you pressed a!')
|
118 | }
|
119 | alert('you pressed a!')
|
120 | });
|
121 |
|
122 | // Key Combination
|
123 | hotkeys('ctrl+a,ctrl+b,r,f', function (event, handler){
|
124 | switch (handler.key) {
|
125 | case 'ctrl+a': alert('you pressed ctrl+a!');
|
126 | break;
|
127 | case 'ctrl+b': alert('you pressed ctrl+b!');
|
128 | break;
|
129 | case 'r': alert('you pressed r!');
|
130 | break;
|
131 | case 'f': alert('you pressed f!');
|
132 | break;
|
133 | default: alert(event);
|
134 | }
|
135 | });
|
136 |
|
137 | hotkeys('ctrl+a+s', function() {
|
138 | alert('you pressed ctrl+a+s!');
|
139 | });
|
140 |
|
141 | // Using a scope
|
142 | hotkeys('*','wcj', function(event){
|
143 | console.log('do something', event);
|
144 | });
|
145 | ```
|
146 |
|
147 | #### option
|
148 |
|
149 | - `scope<String>`
|
150 | - `element<HTMLElement>`
|
151 | - `keyup<Boolean>`
|
152 | - `keydown<Boolean>`
|
153 | - `splitKey<string>` (default is `+`)
|
154 |
|
155 | ```js
|
156 | hotkeys('o, enter', {
|
157 | scope: 'wcj',
|
158 | element: document.getElementById('wrapper'),
|
159 | }, function(){
|
160 | console.log('do something else');
|
161 | });
|
162 |
|
163 | hotkeys('ctrl-+', { splitKey: '-' }, function(e) {
|
164 | console.log('you pressed ctrl and +');
|
165 | });
|
166 |
|
167 | hotkeys('+', { splitKey: '-' }, function(e){
|
168 | console.log('you pressed +');
|
169 | })
|
170 | ```
|
171 |
|
172 | ## API REFERENCE
|
173 |
|
174 | Asterisk "*"
|
175 |
|
176 | Modifier key judgments
|
177 |
|
178 | ```js
|
179 | hotkeys('*', function() {
|
180 | if (hotkeys.shift) {
|
181 | console.log('shift is pressed!');
|
182 | }
|
183 |
|
184 | if (hotkeys.ctrl) {
|
185 | console.log('ctrl is pressed!');
|
186 | }
|
187 |
|
188 | if (hotkeys.alt) {
|
189 | console.log('alt is pressed!');
|
190 | }
|
191 |
|
192 | if (hotkeys.option) {
|
193 | console.log('option is pressed!');
|
194 | }
|
195 |
|
196 | if (hotkeys.control) {
|
197 | console.log('control is pressed!');
|
198 | }
|
199 |
|
200 | if (hotkeys.cmd) {
|
201 | console.log('cmd is pressed!');
|
202 | }
|
203 |
|
204 | if (hotkeys.command) {
|
205 | console.log('command is pressed!');
|
206 | }
|
207 | });
|
208 | ```
|
209 |
|
210 | ### setScope
|
211 |
|
212 | Use the `hotkeys.setScope` method to set scope. There can only be one active scope besides 'all'. By default 'all' is always active.
|
213 |
|
214 | ```js
|
215 | // Define shortcuts with a scope
|
216 | hotkeys('ctrl+o, ctrl+alt+enter', 'issues', function(){
|
217 | console.log('do something');
|
218 | });
|
219 | hotkeys('o, enter', 'files', function(){
|
220 | console.log('do something else');
|
221 | });
|
222 |
|
223 | // Set the scope (only 'all' and 'issues' shortcuts will be honored)
|
224 | hotkeys.setScope('issues'); // default scope is 'all'
|
225 | ```
|
226 |
|
227 | ### getScope
|
228 |
|
229 | Use the `hotkeys.getScope` method to get scope.
|
230 |
|
231 | ```js
|
232 | hotkeys.getScope();
|
233 | ```
|
234 |
|
235 | ### deleteScope
|
236 |
|
237 | Use the `hotkeys.deleteScope` method to delete a scope. This will also remove all associated hotkeys with it.
|
238 |
|
239 | ```js
|
240 | hotkeys.deleteScope('issues');
|
241 | ```
|
242 |
|
243 | ### unbind
|
244 |
|
245 | Similar to defining shortcuts, they can be unbound using `hotkeys.unbind`.
|
246 |
|
247 | ```js
|
248 | // unbind 'a' handler
|
249 | hotkeys.unbind('a');
|
250 |
|
251 | // Unbind a hotkeys only for a single scope
|
252 | // If no scope is specified it defaults to the current scope (hotkeys.getScope())
|
253 | hotkeys.unbind('o, enter', 'issues');
|
254 | hotkeys.unbind('o, enter', 'files');
|
255 | ```
|
256 |
|
257 | Unbind events through functions.
|
258 |
|
259 | ```js
|
260 | function example() {
|
261 | hotkeys('a', example);
|
262 | hotkeys.unbind('a', example);
|
263 |
|
264 | hotkeys('a', 'issues', example);
|
265 | hotkeys.unbind('a', 'issues', example);
|
266 | }
|
267 | ```
|
268 |
|
269 | ### isPressed
|
270 |
|
271 | For example, `hotkeys.isPressed(77)` is true if the `M` key is currently pressed.
|
272 |
|
273 | ```js
|
274 | hotkeys('a', function() {
|
275 | console.log(hotkeys.isPressed('a')); //=> true
|
276 | console.log(hotkeys.isPressed('A')); //=> true
|
277 | console.log(hotkeys.isPressed(65)); //=> true
|
278 | });
|
279 | ```
|
280 |
|
281 | ## keyup
|
282 |
|
283 | **key down** and **key up** both perform callback events.
|
284 |
|
285 | ```js
|
286 | hotkeys('ctrl+a,alt+a+s', {keyup: true}, function(event, handler) {
|
287 | if (event.type === 'keydown') {
|
288 | console.log('keydown:', event.type, handler, handler.key);
|
289 | }
|
290 |
|
291 | if (event.type === 'keyup') {
|
292 | console.log('keyup:', event.type, handler, handler.key);
|
293 | }
|
294 | });
|
295 | ```
|
296 |
|
297 | ### getPressedKeyCodes
|
298 |
|
299 | Returns an array of key codes currently pressed.
|
300 |
|
301 | ```js
|
302 | hotkeys('command+ctrl+shift+a,f', function(){
|
303 | console.log(hotkeys.getPressedKeyCodes()); //=> [17, 65] or [70]
|
304 | })
|
305 | ```
|
306 |
|
307 | ### filter
|
308 |
|
309 | By default hotkeys are not enabled for `INPUT` `SELECT` `TEXTAREA` elements. `Hotkeys.filter` to return to the `true` shortcut keys set to play a role, `false` shortcut keys set up failure.
|
310 |
|
311 | ```js
|
312 | hotkeys.filter = function(event){
|
313 | return true;
|
314 | }
|
315 | //How to add the filter to edit labels. <div contentEditable="true"></div>
|
316 | //"contentEditable" Older browsers that do not support drops
|
317 | hotkeys.filter = function(event) {
|
318 | var tagName = (event.target || event.srcElement).tagName;
|
319 | return !(tagName.isContentEditable || tagName == 'INPUT' || tagName == 'SELECT' || tagName == 'TEXTAREA');
|
320 | }
|
321 |
|
322 | hotkeys.filter = function(event){
|
323 | var tagName = (event.target || event.srcElement).tagName;
|
324 | hotkeys.setScope(/^(INPUT|TEXTAREA|SELECT)$/.test(tagName) ? 'input' : 'other');
|
325 | return true;
|
326 | }
|
327 | ```
|
328 |
|
329 | ### noConflict
|
330 |
|
331 | Relinquish HotKeys’s control of the `hotkeys` variable.
|
332 |
|
333 | ```js
|
334 | var k = hotkeys.noConflict();
|
335 | k('a', function() {
|
336 | console.log("do something")
|
337 | });
|
338 |
|
339 | hotkeys()
|
340 | // -->Uncaught TypeError: hotkeys is not a function(anonymous function)
|
341 | // @ VM2170:2InjectedScript._evaluateOn
|
342 | // @ VM2165:883InjectedScript._evaluateAndWrap
|
343 | // @ VM2165:816InjectedScript.evaluate @ VM2165:682
|
344 | ```
|
345 |
|
346 | ## Development
|
347 |
|
348 | To develop, Install dependencies, Get the code:
|
349 |
|
350 | ```shell
|
351 | $ git https://github.com/jaywcjlove/hotkeys.git
|
352 | $ cd hotkeys # Into the directory
|
353 | $ npm install # or yarn install
|
354 | ```
|
355 |
|
356 | To develop, run the self-reloading build:
|
357 |
|
358 | ```shell
|
359 | $ npm run watch
|
360 | ```
|
361 |
|
362 | Run Document Website Environment.
|
363 |
|
364 | ```shell
|
365 | $ npm run doc:dev
|
366 | ```
|
367 |
|
368 | To contribute, please fork Hotkeys.js, add your patch and tests for it (in the `test/` folder) and submit a pull request.
|
369 |
|
370 | ```shell
|
371 | $ npm run test
|
372 | $ npm run test:watch # Development model
|
373 | ```
|
374 |
|
375 | ## License
|
376 |
|
377 | [MIT © Kenny Wong](./LICENSE)
|