文档管理中心
我的

您当前正在浏览HarmonyOS最新文档,覆盖已发布的所有API版本,可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。

指南与API参考API参考系统基础功能Input Kit(多模输入服务)ArkTS API@ohos.multimodalInput.inputConsumer (全局快捷键)

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

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

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

说明
  • 本模块首批接口从API version 14开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

  • 全局快捷键指由系统或应用定义的组合按键,系统快捷键指由系统定义的全局快捷键,应用快捷键指由应用定义的全局快捷键。

导入模块

收起
自动换行
深色代码主题
复制
  1. import { inputConsumer, KeyEvent } from '@kit.InputKit';

HotkeyOptions

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

快捷键选项。

系统能力: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+

Phone16+PC/2in116+Tablet16+TV19+

按键事件消费设置。

系统能力: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键和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

Phone14+PC/2in114+Tablet14+TV19+

getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>

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

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

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

返回值:

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

错误码:

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

展开
错误码ID 错误信息
801 Capability not supported.

示例:

收起
自动换行
深色代码主题
复制
  1. import { inputConsumer } from '@kit.InputKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. @Entry
  4. @Component
  5. struct Index {
  6. build() {
  7. RelativeContainer() {
  8. Text()
  9. .onClick(() => {
  10. // 获取所有系统热键
  11. inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
  12. console.info(`Succeeded in getting list of system hotkeys: ${JSON.stringify(data)}.`);
  13. }).catch((error: BusinessError) => {
  14. console.error(`Failed to get all system hotkeys, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
  15. })
  16. })
  17. }
  18. }
  19. }

inputConsumer.on('hotkeyChange')

Phone14+PC/2in114+Tablet14+TV19+

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.

示例:

收起
自动换行
深色代码主题
复制
  1. import { inputConsumer } from '@kit.InputKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  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(`Succeeded in consuming hotkey, hotkeyOptions: ${JSON.stringify(hotkeyOptions)}.`);
  19. };
  20. try {
  21. // 订阅热键变更事件
  22. inputConsumer.on('hotkeyChange', hotkeyOptions, hotkeyCallback);
  23. } catch (error) {
  24. console.error(`Failed to Subscribe hot key, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
  25. }
  26. })
  27. }
  28. }
  29. }

inputConsumer.off('hotkeyChange')

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

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.

示例:

收起
自动换行
深色代码主题
复制
  1. import { inputConsumer } from '@kit.InputKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  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(`Succeeded in consuming hotkey, hotkeyOptions: ${JSON.stringify(hotkeyOptions)}.`);
  15. };
  16. let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
  17. try {
  18. // 订阅热键变更事件
  19. inputConsumer.on('hotkeyChange', hotkeyOption, hotkeyCallback);
  20. // 取消订阅热键变更事件
  21. inputConsumer.off('hotkeyChange', hotkeyOption, hotkeyCallback);
  22. console.info(`Succeeded in unsubscribing.`);
  23. } catch (error) {
  24. console.error(`Failed to unsubscribe, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
  25. }
  26. })
  27. }
  28. }
  29. }
收起
自动换行
深色代码主题
复制
  1. import { inputConsumer } from '@kit.InputKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  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(`Succeeded in consuming hotkey, hotkeyOptions: ${JSON.stringify(hotkeyOptions)}.`);
  15. };
  16. let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
  17. try {
  18. // 订阅热键变更事件
  19. inputConsumer.on('hotkeyChange', hotkeyOption, hotkeyCallback);
  20. // 取消订阅热键变更事件
  21. inputConsumer.off('hotkeyChange', hotkeyOption);
  22. console.info(`Succeeded in unsubscribing.`);
  23. } catch (error) {
  24. console.error(`Failed to unsubscribe, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
  25. }
  26. })
  27. }
  28. }
  29. }

inputConsumer.on('keyPressed')16+

Phone16+PC/2in116+Tablet16+TV19+

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

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

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

系统能力: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 是 按键事件消费设置。
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.

示例:

收起
自动换行
深色代码主题
复制
  1. import { inputConsumer, KeyEvent } from '@kit.InputKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  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. // 订阅按键按下事件
  17. inputConsumer.on('keyPressed', options, (event: KeyEvent) => {
  18. console.info(`Succeeded in subscribing ${JSON.stringify(event)}.`);
  19. });
  20. } catch (error) {
  21. console.error(`Failed to subscribe , Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
  22. }
  23. })
  24. }
  25. }
  26. }

inputConsumer.off('keyPressed')16+

Phone16+PC/2in116+Tablet16+TV19+

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> 否 需要取消订阅的回调函数。若缺省,则取消当前已订阅的所有回调函数。

错误码:

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

展开
错误码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';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  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(`Succeeded in unsubscribing ${JSON.stringify(event)}.`);
  19. };
  20. // 订阅按键按下事件
  21. inputConsumer.on('keyPressed', options, callback);
  22. // 取消订阅按键按下事件
  23. inputConsumer.off('keyPressed', callback);
  24. // 取消当前已订阅的所有回调函数
  25. inputConsumer.off('keyPressed');
  26. } catch (error) {
  27. console.error(`Failed to unsubscribe, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
  28. }
  29. })
  30. }
  31. }
  32. }