1# @ohos.multimodalInput.inputConsumer (组合按键)
2
3组合按键订阅模块，用于处理组合按键的订阅。
4
5> **说明：**
6>
7> - 本模块首批接口从API version 14开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9
10## 导入模块
11
12
13```js
14import { inputConsumer } from '@kit.InputKit';
15```
16
17## HotkeyOptions<sup>14+</sup>
18
19快捷键选项。
20
21**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
22
23| 名称        | 类型   | 可读   | 可写   | 说明      |
24| --------- | ------ | ------- | ------- | ------- |
25| preKeys   | Array&lt;number&gt; | 是      | 否      | 修饰键（包括 Ctrl、Shift 和 Alt）集合，数量范围[1, 2]，修饰按键无顺序要求。<br>例如，Ctrl+Shift+Esc中，Ctrl+Shift称为修饰键。 |
26| finalKey  | number  | 是      | 否      | 被修饰键，为除修饰键和 Meta 以外的其它按键。<br>如Ctrl+Shift+Esc中，Esc称为被修饰键。 |
27| isRepeat  | boolean  | 是      | 否      | 是否上报重复的按键事件。true表示上报，false表示不上报，若不填默认为true。 |
28
29## inputConsumer.getAllSystemHotkeys<sup>14+</sup>
30
31getAllSystemHotkeys(): Promise&lt;Array&lt;HotkeyOptions&gt;&gt;
32
33获取系统所有快捷键，使用Promise异步回调。
34
35**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
36
37**返回值：**
38
39| 参数         |  说明                                       |
40| ---------- |  ---------------------------------------- |
41| Promise&lt;Array&lt;HotkeyOptions&gt;&gt;                    | Promise对象，返回所有系统快捷键的列表。 |
42
43**错误码**：
44
45以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
46
47| 错误码ID | 错误信息                  |
48| -------- | ------------------------- |
49| 801      | Capability not supported. |
50
51**示例：**
52
53```js
54inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
55  console.log(`List of system hotkeys : ${JSON.stringify(data)}`);
56});
57```
58
59## inputConsumer.on('hotkeyOptions')<sup>14+</sup>
60
61on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback&lt;HotkeyOptions&gt;): void
62
63订阅全局组合按键，当满足条件的组合按键输入事件发生时，使用Callback异步方式上报组合按键数据。
64
65**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
66
67**参数：**
68
69| 参数名         | 类型                         | 必填   | 说明                                       |
70| ---------- | -------------------------- | ---- | ---------- |
71| type       | string                     | 是    | 事件类型，固定取值为'hotkeyChange'。                   |
72| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | 是    | 快捷键选项。                 |
73| callback   | Callback&lt;HotkeyOptions&gt; | 是    | 回调函数，当满足条件的全局组合按键输入事件发生时，异步上报组合按键数据。 |
74
75**错误码**：
76
77以下错误码的详细介绍请参见[inputconsumer错误码](errorcode-inputconsumer.md)和[通用错误码](../errorcode-universal.md)。
78
79| 错误码ID  | 错误信息             |
80| ---- | --------------------- |
81| 401  | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
82| 801 | Capability not supported. |
83| 4200002  | The hotkey has been used by the system. |
84| 4200003  | The hotkey has been subscribed to by another. |
85
86**示例：**
87
88```js
89let leftCtrlKey = 2072;
90let zKey = 2042;
91let hotkeyOptions: inputConsumer.HotkeyOptions = {
92  preKeys: [ leftCtrlKey ],
93  finalKey: zKey,
94  isRepeat: true
95};
96let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
97  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
98}
99try {
100  inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback);
101} catch (error) {
102  console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
103}
104```
105
106## inputConsumer.off('hotkeyOptions')<sup>14+</sup>
107
108off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback&lt;HotkeyOptions&gt;): void
109
110取消订阅全局组合按键。
111
112**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer
113
114**参数：**
115
116| 参数名         | 类型                         | 必填   | 说明                              |
117| ---------- | -------------------------- | ---- | ---------- |
118| type       | string                     | 是    | 事件类型，固定取值为'hotkeyChange'。        |
119| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | 是    | 快捷键选项。             |
120| callback   | Callback&lt;HotkeyOptions&gt; | 否    | 需要取消订阅的回调函数。若不填，则取消当前应用全局快捷键选项已订阅的所有回调函数。 |
121
122**错误码**：
123
124以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
125
126| 错误码ID  | 错误信息             |
127| ---- | --------------------- |
128| 401  | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
129| 801 | Capability not supported. |
130
131**示例：**
132
133```js
134let leftCtrlKey = 2072;
135let zKey = 2042;
136// 取消订阅单个全局快捷键回调函数
137let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
138  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
139}
140let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
141try {
142  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
143  inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback);
144  console.log(`Unsubscribe success`);
145} catch (error) {
146  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
147}
148```
149```js
150let leftCtrlKey = 2072;
151let zKey = 2042;
152// 取消订阅所有全局快捷键回调函数
153let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
154  console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
155}
156let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true};
157try {
158  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
159  inputConsumer.off("hotkeyChange", hotkeyOption);
160  console.log(`Unsubscribe success`);
161} catch (error) {
162  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
163}
164```