# @ohos.multimodalInput.inputConsumer (全局快捷键)

> phone 14+ | 2in1 14+ | tablet 14+ | tv 19+ | wearable 18+

全局快捷键订阅模块，用于处理组合按键的订阅，本模块也支持音量键拦截监听能力。
> 说明
>
> * 本模块首批接口从API version 14开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
>
> * 全局快捷键指由系统或应用定义的组合按键，系统快捷键指由系统定义的全局快捷键，应用快捷键指由应用定义的全局快捷键。

## 导入模块

> phone | 2in1 | tablet | tv | wearable

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

## HotkeyOptions

> phone 14+ | 2in1 14+ | tablet 14+ | tv 19+ | wearable 18+

快捷键选项。

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

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

## KeyPressedConfig^16+^

> phone 16+ | 2in1 16+ | tablet 16+ | tv 19+

按键事件消费设置。

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

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

|名称|类型|只读|可选|说明|
|:-------|:------|:-|:-|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|key|number|否|否|按键键值。 **说明：** 从API版本26.0.0开始，新增支持[KEYCODE_FINGERPRINT_SLIDE_UP](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键和[KEYCODE_FINGERPRINT_SLIDE_DOWN](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-keycode#keycode)键，非设备通用键值，使用前请判断当前设备是否支持相关按键事件上报，请参考[优先响应系统功能键开发指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/keypressed-guidelines)。 从API version 21开始，新增支持[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

> phone 14+ | 2in1 14+ | tablet 14+ | tv 19+

getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>

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

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

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

**返回值：**

|类型|说明|
|:----------------------------------------------|:----------------------|
|Promise<Array<[HotkeyOptions](#hotkeyoptions)>>|Promise对象，返回所有系统快捷键的列表。|

**错误码**：

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

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

**示例：**

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

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // 获取所有系统热键
          inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
            console.info(`Succeeded in getting list of system hotkeys: ${JSON.stringify(data)}.`);
          }).catch((error: BusinessError) => {
            console.error(`Failed to get all system hotkeys, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          })
        })
    }
  }
}
```

## inputConsumer.on('hotkeyChange')

> phone 14+ | 2in1 14+ | tablet 14+ | tv 19+

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

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

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

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

**参数：**

|参数名|类型|必填|说明|
|:------------|:----------------------------------------|:-|:------------------------|
|type|string|是|事件类型，固定取值为'hotkeyChange'。|
|hotkeyOptions|[HotkeyOptions](#hotkeyoptions)|是|快捷键选项。|
|callback|Callback<[HotkeyOptions](#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.|

**示例：**

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

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let leftCtrlKey = 2072;
          let zKey = 2042;
          let hotkeyOptions: inputConsumer.HotkeyOptions = {
            preKeys: [leftCtrlKey],
            finalKey: zKey,
            isRepeat: true
          };
          let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
            console.info(`Succeeded in consuming hotkey, hotkeyOptions: ${JSON.stringify(hotkeyOptions)}.`);
          };
          try {
            // 订阅热键变更事件
            inputConsumer.on('hotkeyChange', hotkeyOptions, hotkeyCallback);
          } catch (error) {
            console.error(`Failed to Subscribe hot key, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}
```

## inputConsumer.off('hotkeyChange')

> phone 14+ | 2in1 14+ | tablet 14+ | tv 19+ | wearable 18+

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

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

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

**参数：**

|参数名|类型|必填|说明|
|:------------|:----------------------------------------|:-|:--------------------------------------|
|type|string|是|事件类型，固定取值为'hotkeyChange'。|
|hotkeyOptions|[HotkeyOptions](#hotkeyoptions)|是|快捷键选项。|
|callback|Callback<[HotkeyOptions](#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.|

**示例：**

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

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let leftCtrlKey = 2072;
          let zKey = 2042;
          // 取消订阅单个应用快捷键回调函数
          let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
            console.info(`Succeeded in consuming hotkey, hotkeyOptions: ${JSON.stringify(hotkeyOptions)}.`);
          };
          let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
          try {
            // 订阅热键变更事件
            inputConsumer.on('hotkeyChange', hotkeyOption, hotkeyCallback);
            // 取消订阅热键变更事件
            inputConsumer.off('hotkeyChange', hotkeyOption, hotkeyCallback);
            console.info(`Succeeded in unsubscribing.`);
          } catch (error) {
            console.error(`Failed to unsubscribe, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}
```

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

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let leftCtrlKey = 2072;
          let zKey = 2042;
          // 取消订阅所有应用快捷键回调函数
          let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
            console.info(`Succeeded in consuming hotkey, hotkeyOptions: ${JSON.stringify(hotkeyOptions)}.`);
          };
          let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
          try {
            // 订阅热键变更事件
            inputConsumer.on('hotkeyChange', hotkeyOption, hotkeyCallback);
            // 取消订阅热键变更事件
            inputConsumer.off('hotkeyChange', hotkeyOption);
            console.info(`Succeeded in unsubscribing.`);
          } catch (error) {
            console.error(`Failed to unsubscribe, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}
```

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

> phone 16+ | 2in1 16+ | tablet 16+ | tv 19+

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

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

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

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

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

**参数：**

|参数名|类型|必填|说明|
|:-------|:----------------------------------------------------------------------------------------------------------------|:-|:--------------------------------------------|
|type|string|是|事件类型，固定取值为'keyPressed'。|
|options|[KeyPressedConfig](#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.|

**示例：**

```js
import { inputConsumer, KeyEvent } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            let options: inputConsumer.KeyPressedConfig = {
              key: 16,
              action: 1,
              isRepeat: false,
            }
            // 订阅按键按下事件
            inputConsumer.on('keyPressed', options, (event: KeyEvent) => {
              console.info(`Succeeded in subscribing ${JSON.stringify(event)}.`);
            });
          } catch (error) {
            console.error(`Failed to subscribe , Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}
```

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

> phone 16+ | 2in1 16+ | tablet 16+ | tv 19+

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

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

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

**设备行为差异**：API version 19之前，该接口在Phone、Tablet和PC/2in1设备中可正常调用，在其他设备上返回801错误码。从API version 19开始，该接口在Phone、Tablet、PC/2in1和TV设备中可正常调用，在其他设备上返回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.|

**示例：**

```js
import { inputConsumer, KeyEvent } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            // 取消指定回调函数
            let options: inputConsumer.KeyPressedConfig = {
              key: 16,
              action: 1,
              isRepeat: false,
            }
            let callback = (event: KeyEvent) => {
              console.info(`Succeeded in unsubscribing ${JSON.stringify(event)}.`);
            };
            // 订阅按键按下事件
            inputConsumer.on('keyPressed', options, callback);
            // 取消订阅按键按下事件
            inputConsumer.off('keyPressed', callback);
            // 取消当前已订阅的所有回调函数
            inputConsumer.off('keyPressed');
          } catch (error) {
            console.error(`Failed to unsubscribe, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}
```