全局快捷键订阅模块，用于处理组合按键的订阅，本模块也支持音量键拦截监听能力。

说明

* 本模块首批接口从API version 14开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
* 全局快捷键指由系统或应用定义的组合按键，系统快捷键指由系统定义的全局快捷键，应用快捷键指由应用定义的全局快捷键。

## 导入模块

PhonePC/2in1TabletTVWearable



```
1. import { inputConsumer, KeyEvent } from '@kit.InputKit';
```

## HotkeyOptions

PhonePC/2in1TabletTVWearable

快捷键选项。

**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| preKeys | Array<number> | 否 | 否 | 修饰键（包括 Ctrl、Shift 和 Alt）集合，数量范围[1, 2]，无顺序要求。  例如，Ctrl+Shift+Esc中，Ctrl+Shift称为修饰键。 |
| finalKey | number | 否 | 否 | 被修饰键，除修饰键和Meta键以外的按键，详细按键介绍请参见[键值](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode)。  例如，Ctrl+Shift+Esc中，Esc称为被修饰键。 |
| isRepeat | boolean | 否 | 是 | 是否上报重复的按键事件。true表示上报，false表示不上报，默认值为true。 |

## KeyPressedConfig16+

PhonePC/2in1TabletTVWearable

按键事件消费设置。

**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer

**设备行为差异**：API version 23之前，该接口在Phone和Tablet设备中可正常调用，在其他设备上返回801错误码。从API version 23开始，该接口在Phone、Tablet、PC/2in1、TV和Car设备中可正常调用，在其他设备上返回801错误码。

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| key | number | 否 | 否 | 按键键值。  **说明：** 从API version 21开始，支持[KEYCODE\_VOLUME\_UP](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键、[KEYCODE\_VOLUME\_DOWN](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键、[KEYCODE\_MEDIA\_PLAY\_PAUSE](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键、[KEYCODE\_MEDIA\_NEXT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键和[KEYCODE\_MEDIA\_PREVIOUS](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键。  对于API version 20及之前的版本，仅支持[KEYCODE\_VOLUME\_UP](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键和[KEYCODE\_VOLUME\_DOWN](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键。 |
| action | number | 否 | 否 | 订阅指定的按键事件。  **说明：** 从API version 21开始，支持取值为1和2，取值为1表示订阅按键按下事件，取值为2表示同时订阅按键按下事件和按键抬起事件。  对于API version 20及之前的版本，仅支持取值为1，表示订阅按键按下事件。 |
| isRepeat | boolean | 否 | 否 | 是否上报重复的按键事件。true表示上报，false表示不上报，默认值为true。 |

## inputConsumer.getAllSystemHotkeys

PhonePC/2in1TabletTVWearable

getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>

获取所有系统快捷键，使用Promise异步回调。

**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer

**设备行为差异**：该接口在Wearable设备上返回801错误码，在其他设备上可正常调用。

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| Promise<Array<HotkeyOptions>> | Promise对象，返回所有系统快捷键的列表。 |

**错误码**：

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 801 | Capability not supported. |

**示例：**



```
1. import { inputConsumer } from '@kit.InputKit';
2. import { BusinessError } from '@kit.BasicServicesKit';

4. @Entry
5. @Component
6. struct Index {
7. build() {
8. RelativeContainer() {
9. Text()
10. .onClick(() => {
11. inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
12. console.info(`List of system hotkeys : ${JSON.stringify(data)}`);
13. }).catch((error: BusinessError) => {
14. console.error(`Get all system hotkeys failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
15. })
16. })
17. }
18. }
19. }
```

## inputConsumer.on('hotkeyChange')

PhonePC/2in1TabletTVWearable

on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void

订阅应用快捷键。获取满足条件的组合按键输入事件，使用callback异步回调。

**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer

**设备行为差异**：该接口在Wearable设备上返回801错误码，在其他设备上可正常调用。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'hotkeyChange'。 |
| hotkeyOptions | [HotkeyOptions](/consumer/cn/doc/harmonyos-references/js-apis-inputconsumer#hotkeyoptions) | 是 | 快捷键选项。 |
| callback | Callback<HotkeyOptions> | 是 | 回调函数，获取满足条件的组合按键输入事件。 |

**错误码**：

以下错误码的详细介绍请参见[全局快捷键管理错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-inputconsumer)和[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. |
| 4200002 | The hotkey has been used by the system. |
| 4200003 | The hotkey has been subscribed to by another. |

**示例：**



```
1. import { inputConsumer } from '@kit.InputKit';

3. @Entry
4. @Component
5. struct Index {
6. build() {
7. RelativeContainer() {
8. Text()
9. .onClick(() => {
10. let leftCtrlKey = 2072;
11. let zKey = 2042;
12. let hotkeyOptions: inputConsumer.HotkeyOptions = {
13. preKeys: [leftCtrlKey],
14. finalKey: zKey,
15. isRepeat: true
16. };
17. let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
18. console.info(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
19. }
20. try {
21. inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback);
22. } catch (error) {
23. console.error(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
24. }
25. })
26. }
27. }
28. }
```

## inputConsumer.off('hotkeyChange')

PhonePC/2in1TabletTVWearable

off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void

取消订阅应用快捷键。使用callback异步回调。

**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer

**设备行为差异**：该接口在Wearable设备上返回801错误码，在其他设备上可正常调用。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'hotkeyChange'。 |
| hotkeyOptions | [HotkeyOptions](/consumer/cn/doc/harmonyos-references/js-apis-inputconsumer#hotkeyoptions) | 是 | 快捷键选项。 |
| callback | Callback<HotkeyOptions> | 否 | 需要取消订阅的回调函数。若缺省，则取消当前应用快捷键选项已订阅的所有回调函数。 |

**错误码**：

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. |

**示例：**



```
1. import { inputConsumer } from '@kit.InputKit';

3. @Entry
4. @Component
5. struct Index {
6. build() {
7. RelativeContainer() {
8. Text()
9. .onClick(() => {
10. let leftCtrlKey = 2072;
11. let zKey = 2042;
12. // 取消订阅单个应用快捷键回调函数
13. let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
14. console.info(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
15. }
16. let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
17. try {
18. inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
19. inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback);
20. console.info(`Unsubscribe success`);
21. } catch (error) {
22. console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
23. }
24. })
25. }
26. }
27. }
```



```
1. import { inputConsumer } from '@kit.InputKit';

3. @Entry
4. @Component
5. struct Index {
6. build() {
7. RelativeContainer() {
8. Text()
9. .onClick(() => {
10. let leftCtrlKey = 2072;
11. let zKey = 2042;
12. // 取消订阅所有应用快捷键回调函数
13. let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
14. console.info(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
15. }
16. let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
17. try {
18. inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
19. inputConsumer.off("hotkeyChange", hotkeyOption);
20. console.info(`Unsubscribe success`);
21. } catch (error) {
22. console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
23. }
24. })
25. }
26. }
27. }
```

## inputConsumer.on('keyPressed')16+

PhonePC/2in1TabletTVWearable

on(type: 'keyPressed', options: KeyPressedConfig, callback: Callback<KeyEvent>): void

订阅按键按下事件，使用callback异步回调。若当前应用窗口为前台焦点窗口，用户按下指定按键，会触发回调。

订阅成功后，该按键事件的系统默认行为将被屏蔽，即不会再触发系统级的响应，如音量调节。要恢复系统响应，请使用[off](/consumer/cn/doc/harmonyos-references/js-apis-inputconsumer#inputconsumeroffkeypressed16)方法取消订阅。

**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer

**设备行为差异**：API version 23之前，该接口在Phone和Tablet设备中可正常调用，在其他设备上返回801错误码。从API version 23开始，该接口在Phone、Tablet、PC/2in1、TV和Car设备中可正常调用，在其他设备上返回801错误码。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'keyPressed'。 |
| options | [KeyPressedConfig](/consumer/cn/doc/harmonyos-references/js-apis-inputconsumer#keypressedconfig16) | 是 | 按键事件消费设置。 |
| callback | Callback<[KeyEvent](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keyevent#keyevent)> | 是 | 回调函数，用于返回按键事件。订阅不同的按键事件需要使用不同的callback，否则订阅不生效。 |

**错误码**：

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. |

**示例：**



```
1. import { inputConsumer, KeyEvent } from '@kit.InputKit';

3. @Entry
4. @Component
5. struct Index {
6. build() {
7. RelativeContainer() {
8. Text()
9. .onClick(() => {
10. try {
11. let options: inputConsumer.KeyPressedConfig = {
12. key: 16,
13. action: 1,
14. isRepeat: false,
15. }
16. inputConsumer.on('keyPressed', options, (event: KeyEvent) => {
17. console.info(`Subscribe success ${JSON.stringify(event)}`);
18. });
19. } catch (error) {
20. console.error(`Subscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
21. }
22. })
23. }
24. }
25. }
```

## inputConsumer.off('keyPressed')16+

PhonePC/2in1TabletTVWearable

off(type: 'keyPressed', callback?: Callback<KeyEvent>): void

取消对'keyPressed'事件的订阅，使用callback异步回调。调用该方法后，被屏蔽的系统按键默认行为将恢复，即系统对音量调节等默认响应将恢复。

**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer

**设备行为差异**：API version 23之前，该接口在Phone和Tablet设备中可正常调用，在其他设备上返回801错误码。从API version 23开始，该接口在Phone、Tablet、PC/2in1、TV和Car设备中可正常调用，在其他设备上返回801错误码。

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'keyPressed'。 |
| callback | Callback<[KeyEvent](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keyevent#keyevent)> | 否 | 需要取消订阅的回调函数。若缺省，则取消当前已订阅的所有回调函数。 |

**错误码**：

以下错误码的详细介绍请参见[通用错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-universal)。

展开

| 错误码ID | 错误信息 |
| --- | --- |
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. |
| 801 | Capability not supported. |

**示例：**



```
1. import { inputConsumer, KeyEvent } from '@kit.InputKit';

3. @Entry
4. @Component
5. struct Index {
6. build() {
7. RelativeContainer() {
8. Text()
9. .onClick(() => {
10. try {
11. // 取消指定回调函数
12. let options: inputConsumer.KeyPressedConfig = {
13. key: 16,
14. action: 1,
15. isRepeat: false,
16. }
17. let callback = (event: KeyEvent) => {
18. console.info(`Unsubscribe success ${JSON.stringify(event)}`);
19. }
20. inputConsumer.on('keyPressed', options, callback);
21. inputConsumer.off('keyPressed', callback);
22. // 取消当前已订阅的所有回调函数
23. inputConsumer.off("keyPressed");
24. } catch (error) {
25. console.error(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
26. }
27. })
28. }
29. }
30. }
```