📦 doouding / keybinding

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
> # ⚠️ This project is no longer being maintained.

# Keybinding
![npm](https://img.shields.io/npm/v/keybinding)
![npm](https://img.shields.io/badge/no-dependencies-green)
![npm](https://img.shields.io/badge/coverage-88%25-green)
![build-and-test](https://github.com/codertx/keybinding/workflows/build-and-test/badge.svg?branch=master&event=push)

A typescript library to handle hotkeys in browser.

## Usage

```bash
$ yarn add keybinding
```

```javascript
import Keybinding from 'keybinding';

const keybinding = new Keybinding();

keybinding.on('ctrl + a', () => {
    console.log('ctrl + a pressed!');
});
```

### Supported Keys

Keybinding support function keys, common modifier keys and some special keys. You can use their handy name to bind event.

- Function keys: `f1` - `f12`
- Shift: `shift`
- Meta: `meta`, `windows`, `command`, `cmd` 
- Control: `control`, `ctrl`
- Alt: `alt`, `option`
- Space: `space`
- Arrow keys: `up`, `down`, `left`, `right`
- Backspace: `backspace`, `back`
- Enter: `enter`
- Alphabet keys: `a` - `z` and `A` - `Z`
- Number keys: `0` - `9`
- Punctuation keys: `` ` ``,`-`, `+`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/` 

### API

**construct options**
```typescript
interface IKeybindingOptions {
    /**
     * Do not call handler when focus on editable element.
     * Default to true.
     */
    filterEditable: boolean;
}

new Keybinding(options?: IKeybindingOptions);
```

**on**

Add a hotkey handler.

```typescript
/**
 * @param key hotkey string
 * @param handler callback function when the hotkey pressed
 * @param scope the scope which bind at, use 'default' by default
 */
keybinding.on(key: string, handler: (keybind: Keybinding) => any, scope?: string): void

keybind.on('ctrl + a', () => {
    console.log('ctrl + a pressed')!
});

// Key is case-insensitive and space-trimming. Thus, the following two calls are equal.
keybind.on('cTRl    +       A', console.log);
keybind.on('ctrl+a', console.log);
```

**off**

Remove a hotkey handler.

```typescript
/**
 * @param key hotkey string
 * @param handler callback function to remove
 * @param scope the scope which bind at, use 'default' by default
 */
keybinding.off(key: string, handler: (keybind: Keybinding) => any, scope?: string): void

keybind.off('ctrl + a', aBoundHandler);
```

> Scopes are used to control whether handler should be called when the bound hotkey was pressed. See more detail in `disable`/`enable` method.

**disable/enable**

`disable` method will disable the given scope's handlers. All handlers under the given scope will not be called even if the hotkeys they bound was pressed until the `enable` method called. 

```typescript
/**
 * Disable given scope's hotkeys.
 * @param scope scope to disable, use 'all' by default
 */
keybinding.disable(scope?: string);
/**
 * Enable given scope's hotkeys
 * @param scope Scope to enable, use 'all' by default
 */
keybinding.enable(scope?: string);

// After pressing Control + A, handlerA won't be called but handlerB will still be called.
keybind.on('ctrl + a', handlerA);
keybind.on('ctrl + a', handlerB, 'scope2');
keybind.disable('default');

// You can choose to pass no parameter to disable all handler.
// In the following example, both handlerC and handlerD won't be called.
keybind.on('ctrl + a', handlerC, 'scope');
keybind.on('ctrl + a', handlerD, 'scope2');
keybind.disable();   // equal to keybind.disable('all')

// use enable to restore given  disabled scope
keybind.enable('scope1')    // enable 'scope1'
keybind.enable()            // enable all scope, equal to keybind.disable('all')
```

**destroy**

Destroy instance.

```typescript
keybind.destroy();
```