@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。

KeyPressedConfig¹⁶⁺

按键事件消费设置。

系统能力： 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';

@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';

@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';

@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')¹⁶⁺

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

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

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

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

参数：

参数名	类型	必填	说明
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';

@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')¹⁶⁺

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

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

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

参数：

参数名	类型	必填	说明
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';

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

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

导入模块

HotkeyOptions

KeyPressedConfig16+

inputConsumer.getAllSystemHotkeys

inputConsumer.on('hotkeyChange')

inputConsumer.off('hotkeyChange')

inputConsumer.on('keyPressed')16+

inputConsumer.off('keyPressed')16+

KeyPressedConfig¹⁶⁺

inputConsumer.on('keyPressed')¹⁶⁺

inputConsumer.off('keyPressed')¹⁶⁺