1# @ohos.multimodalInput.inputConsumer (组合按键) 2 3组合按键订阅模块，用于处理组合按键的订阅。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 14开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12 13```js 14import { inputConsumer, KeyEvent } from '@kit.InputKit'; 15``` 16 17## HotkeyOptions<sup>14+</sup> 18 19快捷键选项。 20 21**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 22 23| 名称 | 类型 | 可读 | 可写 | 说明 | 24| --------- | ------ | ------- | ------- | ------- | 25| preKeys | Array<number> | 是 | 否 | 修饰键（包括 Ctrl、Shift 和 Alt）集合，数量范围[1, 2]，修饰按键无顺序要求。<br>例如，Ctrl+Shift+Esc中，Ctrl+Shift称为修饰键。 | 26| finalKey | number | 是 | 否 | 被修饰键，为除修饰键和 Meta 以外的其它按键。<br>如Ctrl+Shift+Esc中，Esc称为被修饰键。 | 27| isRepeat | boolean | 是 | 否 | 是否上报重复的按键事件。true表示上报，false表示不上报，若不填默认为true。 | 28 29## KeyPressedConfig<sup>16+</sup> 30 31按键事件消费设置。 32 33**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 34 35| 名称 | 类型 | 可读 | 可写 | 说明 | 36| --------- | ------ | ------- | ------- | ------- | 37| key | number | 是 | 否 | 按键键值。<br>当前仅支持[KEYCODE_VOLUME_UP](js-apis-keycode.md#keycode)键和[KEYCODE_VOLUME_DOWN](js-apis-keycode.md#keycode)键。 | 38| action | number | 是 | 否 | 按键事件类型。取值如下，当前仅支持取值为1。<br>- 1：按键按下。<br>- 2：按键抬起。 | 39| isRepeat | boolean | 是 | 否 | 是否上报重复的按键事件。 | 40 41## inputConsumer.getAllSystemHotkeys<sup>14+</sup> 42 43getAllSystemHotkeys(): Promise<Array<HotkeyOptions>> 44 45获取系统所有快捷键，使用Promise异步回调。 46 47**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 48 49**返回值：** 50 51| 参数 | 说明 | 52| ---------- | ---------------------------------------- | 53| Promise<Array<HotkeyOptions>> | Promise对象，返回所有系统快捷键的列表。 | 54 55**错误码**： 56 57以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 58 59| 错误码ID | 错误信息 | 60| -------- | ------------------------- | 61| 801 | Capability not supported. | 62 63**示例：** 64 65```js 66inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => { 67 console.log(`List of system hotkeys : ${JSON.stringify(data)}`); 68}); 69``` 70 71## inputConsumer.on('hotkeyChange')<sup>14+</sup> 72 73on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void 74 75订阅全局组合按键，当满足条件的组合按键输入事件发生时，使用Callback异步方式上报组合按键数据。 76 77**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 78 79**参数：** 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ---------- | -------------------------- | ---- | ---------- | 83| type | string | 是 | 事件类型，固定取值为'hotkeyChange'。 | 84| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | 是 | 快捷键选项。 | 85| callback | Callback<HotkeyOptions> | 是 | 回调函数，当满足条件的全局组合按键输入事件发生时，异步上报组合按键数据。 | 86 87**错误码**： 88 89以下错误码的详细介绍请参见[inputconsumer错误码](errorcode-inputconsumer.md)和[通用错误码](../errorcode-universal.md)。 90 91| 错误码ID | 错误信息 | 92| ---- | --------------------- | 93| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 94| 801 | Capability not supported. | 95| 4200002 | The hotkey has been used by the system. | 96| 4200003 | The hotkey has been subscribed to by another. | 97 98**示例：** 99 100```js 101let leftCtrlKey = 2072; 102let zKey = 2042; 103let hotkeyOptions: inputConsumer.HotkeyOptions = { 104 preKeys: [ leftCtrlKey ], 105 finalKey: zKey, 106 isRepeat: true 107}; 108let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => { 109 console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`); 110} 111try { 112 inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback); 113} catch (error) { 114 console.log(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 115} 116``` 117 118## inputConsumer.off('hotkeyChange')<sup>14+</sup> 119 120off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void 121 122取消订阅全局组合按键。 123 124**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ---------- | -------------------------- | ---- | ---------- | 130| type | string | 是 | 事件类型，固定取值为'hotkeyChange'。 | 131| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | 是 | 快捷键选项。 | 132| callback | Callback<HotkeyOptions> | 否 | 需要取消订阅的回调函数。若不填，则取消当前应用全局快捷键选项已订阅的所有回调函数。 | 133 134**错误码**： 135 136以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 137 138| 错误码ID | 错误信息 | 139| ---- | --------------------- | 140| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 141| 801 | Capability not supported. | 142 143**示例：** 144 145```js 146let leftCtrlKey = 2072; 147let zKey = 2042; 148// 取消订阅单个全局快捷键回调函数 149let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => { 150 console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`); 151} 152let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true}; 153try { 154 inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback); 155 inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback); 156 console.log(`Unsubscribe success`); 157} catch (error) { 158 console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 159} 160``` 161 162```js 163let leftCtrlKey = 2072; 164let zKey = 2042; 165// 取消订阅所有全局快捷键回调函数 166let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => { 167 console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`); 168} 169let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true}; 170try { 171 inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback); 172 inputConsumer.off("hotkeyChange", hotkeyOption); 173 console.log(`Unsubscribe success`); 174} catch (error) { 175 console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 176} 177``` 178 179## inputConsumer.on('keyPressed')<sup>16+</sup> 180 181on(type: 'keyPressed', options: KeyPressedConfig, callback: Callback<KeyEvent>): void 182 183订阅按键按下事件。若当前应用处于前台焦点窗口，用户按下指定按键，会触发回调。 184 185**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 186 187**参数：** 188 189| 参数名 | 类型 | 必填 | 说明 | 190| ---------- | -------------------------- | ---- | ---------- | 191| type | string | 是 | 事件类型，固定取值为'keyPressed'。 | 192| options | [KeyPressedConfig](#keypressedconfig16)| 是 | 按键事件消费设置。 | 193| callback | Callback<[KeyEvent](./js-apis-keyevent.md#keyevent)> | 是 | 用于返回按键事件的回调函数。 | 194 195**错误码**： 196 197以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 198 199| 错误码ID | 错误信息 | 200| ---- | --------------------- | 201| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 202| 801 | Capability not supported. | 203 204**示例：** 205 206```js 207try { 208 let options: inputConsumer.KeyPressedConfig = { 209 key: 16, 210 action: 1, 211 isRepeat: false, 212 } 213 inputConsumer.on('keyPressed', options, (event: KeyEvent) => { 214 console.log(`Subscribe success ${JSON.stringify(event)}`); 215 }); 216} catch (error) { 217 console.log(`Subscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 218} 219``` 220 221## inputConsumer.off('keyPressed')<sup>16+</sup> 222 223off(type: 'keyPressed', callback?: Callback<KeyEvent>): void 224 225取消按键按下事件订阅。 226 227**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| ---------- | -------------------------- | ---- | ---------- | 233| type | string | 是 | 事件类型，固定取值为'keyPressed'。 | 234| callback | Callback<[KeyEvent](./js-apis-keyevent.md#keyevent)> | 否 | 需要取消订阅的回调函数。若不填，则取消当前已订阅的所有回调函数。 | 235 236**错误码**： 237 238以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 239 240| 错误码ID | 错误信息 | 241| ---- | --------------------- | 242| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 243| 801 | Capability not supported. | 244 245**示例：** 246 247```js 248try { 249 // 取消指定回调函数 250 inputConsumer.off('keyPressed', (event: KeyEvent) => { 251 console.log(`Unsubscribe success ${JSON.stringify(event)}`); 252 }); 253 // 取消当前已订阅的所有回调函数 254 inputConsumer.off("keyPressed"); 255} catch (error) { 256 console.log(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 257} 258``` 259 260 261