-
本模块首批接口从API version 14开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
-
全局快捷键指由系统或应用定义的组合按键,系统快捷键指由系统定义的全局快捷键,应用快捷键指由应用定义的全局快捷键。
您当前正在浏览HarmonyOS最新文档,覆盖已发布的所有API版本,可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
全局快捷键订阅模块,用于处理组合按键的订阅,本模块也支持音量键拦截监听能力。
本模块首批接口从API version 14开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
全局快捷键指由系统或应用定义的组合按键,系统快捷键指由系统定义的全局快捷键,应用快捷键指由应用定义的全局快捷键。
- import { inputConsumer, KeyEvent } from '@kit.InputKit';
快捷键选项。
系统能力: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。 |
按键事件消费设置。
系统能力: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。 |
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}.`);
- })
- })
- }
- }
- }
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}.`);
- }
- })
- }
- }
- }
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}.`);
- }
- })
- }
- }
- }
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. |
示例:
- 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}.`);
- }
- })
- }
- }
- }
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. |
示例:
- 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}.`);
- }
- })
- }
- }
- }