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

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

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

#### 导入模块

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

#### HotkeyOptions

快捷键选项。

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

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

#### KeyPressedConfig16+

按键事件消费设置。

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

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

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| key | number | 否 | 否 | 按键键值。 说明： 从API version 26.0.0开始，新增支持KEYCODE_FINGERPRINT_SLIDE_UP键和KEYCODE_FINGERPRINT_SLIDE_DOWN键，非设备通用键值，使用前请判断当前设备是否支持相关按键事件上报，请参考优先响应系统功能键开发指导。 从API version 21开始，新增支持KEYCODE_MEDIA_PLAY_PAUSE键、KEYCODE_MEDIA_NEXT键和KEYCODE_MEDIA_PREVIOUS键。 对于API version 20及之前的版本，仅支持KEYCODE_VOLUME_UP键和KEYCODE_VOLUME_DOWN键。 |
| action | number | 否 | 否 | 订阅指定的按键事件。 说明： 从API version 21开始，支持取值为1和2，取值为1表示订阅按键按下事件，取值为2表示同时订阅按键按下事件和按键抬起事件。 对于API version 20及之前的版本，仅支持取值为1，表示订阅按键按下事件。 |
| isRepeat | boolean | 否 | 否 | 是否上报重复的按键事件。true表示上报，false表示不上报，默认值为true。 |

#### inputConsumer.getAllSystemHotkeys

getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>

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

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

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

**返回值：**

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

**错误码**：

以下错误码的详细介绍请参见通用错误码。

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

**示例：**

```
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')

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

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

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'hotkeyChange'。 |
| hotkeyOptions | HotkeyOptions | 是 | 快捷键选项。 |
| callback | Callback<HotkeyOptions> | 是 | 回调函数，返回满足条件的组合按键输入事件。 |

**错误码**：

以下错误码的详细介绍请参见全局快捷键管理错误码和通用错误码。

| 错误码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. |

**示例：**

```
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')

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

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'hotkeyChange'。 |
| hotkeyOptions | HotkeyOptions | 是 | 快捷键选项。 |
| callback | Callback<HotkeyOptions> | 否 | 需要取消订阅的回调函数。若缺省，则取消当前应用快捷键选项已订阅的所有回调函数。 |

**错误码**：

以下错误码的详细介绍请参见通用错误码。

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

**示例：**

```
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}.`);
          }
        })
    }
  }
}
```

```
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+

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

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

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

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

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

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'keyPressed'。 |
| options | KeyPressedConfig | 是 | 按键事件消费设置。 |
| callback | Callback<KeyEvent> | 是 | 回调函数，返回按键事件。订阅不同的按键事件需要使用不同的callback，否则订阅不生效。 |

**错误码**：

以下错误码的详细介绍请参见通用错误码。

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

**示例：**

```
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+

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设备中可正常调用，在其他设备上返回801错误码。

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 事件类型，固定取值为'keyPressed'。 |
| callback | Callback<KeyEvent> | 否 | 需要取消订阅的回调函数。若缺省，则取消当前已订阅的所有回调函数。 |

**错误码**：

以下错误码的详细介绍请参见通用错误码。

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

**示例：**

```
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}.`);
          }
        })
    }
  }
}
```