1# @ohos.multimodalInput.inputConsumer (Input Consumer) 2 3The **inputConsumer** module implements listening for combination key events. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 14. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12 13```js 14import { inputConsumer } from '@kit.InputKit'; 15``` 16 17## HotkeyOptions<sup>14+</sup> 18 19Defines shortcut key options. 20 21**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 22 23| Name | Type | Readable | Writable | Description | 24| --------- | ------ | ------- | ------- | ------- | 25| preKeys | Array<number> | Yes | No | Modifier key set (including Ctrl, Shift, and Alt). A maximum of two modifier keys are supported. There is no requirement on the sequence of modifier keys.<br>For example, in **Ctrl+Shift+Esc**, **Ctrl** and **Shift** are modifier keys.| 26| finalKey | number | Yes | No | Modified key, which is the key other than the modifier key and meta key.<br>For example, in **Ctrl+Shift+Esc**, **Esc** is the modified key.| 27| isRepeat | boolean | Yes | No | Whether to report repeated key events. The value **true** means to report repeated key events, and the value **false** means the opposite. The default value is **true**.| 28 29## KeyPressedConfig<sup>16+</sup> 30 31Sets the key event consumption configuration. 32 33**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 34 35| Name | Type | Readable | Writable | Description | 36| --------- | ------ | ------- | ------- | ------- | 37| key | number | Yes | No | Key value.<br>Currently, only the [KEYCODE_VOLUME_UP](js-apis-keycode.md#keycode) and [KEYCODE_VOLUME_DOWN](js-apis-keycode.md#keycode) keys are supported.| 38| action | number | Yes | No | Key event type. Currently, the value can only be **1**.<br>- **1**: Key press.<br>- **2**: Key release.| 39| isRepeat | boolean | Yes | No | Whether to report repeated key events.| 40 41## inputConsumer.getAllSystemHotkeys<sup>14+</sup> 42 43getAllSystemHotkeys(): Promise<Array<HotkeyOptions>> 44 45Obtains all system shortcut keys. This API uses a promise to return the result. 46 47**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 48 49**Return value** 50 51| Parameter | Description | 52| ---------- | ---------------------------------------- | 53| Promise<Array<HotkeyOptions>> | Promise used to return the list of all system shortcut keys.| 54 55**Error codes**: 56 57For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 58 59| Error Code| Error Message | 60| -------- | ------------------------- | 61| 801 | Capability not supported. | 62 63**Example** 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('hotkeyOptions')<sup>14+</sup> 72 73on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void 74 75Enables listening for global combination key events. This API uses an asynchronous callback to return the combination key data when a combination key event that meets the specified condition occurs. 76 77**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 78 79**Parameters** 80 81| Name | Type | Mandatory | Description | 82| ---------- | -------------------------- | ---- | ---------- | 83| type | string | Yes | Event type. This parameter has a fixed value of **hotkeyChange**. | 84| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | Yes | Shortcut key options. | 85| callback | Callback<HotkeyOptions> | Yes | Callback used to return the combination key data when a global combination key event that meets the specified condition occurs.| 86 87**Error codes**: 88 89For details about the error codes, see [Input Consumer Error Codes](errorcode-inputconsumer.md) and [Universal Error Codes](../errorcode-universal.md). 90 91| Error Code | Error Message | 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**Example** 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('hotkeyOptions')<sup>14+</sup> 119 120off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void 121 122Disables listening for global combination key events. 123 124**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 125 126**Parameters** 127 128| Name | Type | Mandatory | Description | 129| ---------- | -------------------------- | ---- | ---------- | 130| type | string | Yes | Event type. This parameter has a fixed value of **hotkeyChange**. | 131| hotkeyOptions | [HotkeyOptions](#hotkeyoptions14) | Yes | Shortcut key options. | 132| callback | Callback<HotkeyOptions> | No | Callback to unregister. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.| 133 134**Error codes**: 135 136For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 137 138| Error Code | Error Message | 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**Example** 144 145```js 146let leftCtrlKey = 2072; 147let zKey = 2042; 148// Disable listening for a single callback. 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// Disable listening for all callbacks. 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 183Subscribes to key press events. If the current application is in the foreground focus window, a callback is triggered when the specified key is pressed. 184 185**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 186 187**Parameters** 188 189| Name | Type | Mandatory | Description | 190| ---------- | -------------------------- | ---- | ---------- | 191| type | string | Yes | Event type. This parameter has a fixed value of **keyPressed**. | 192| options | [KeyPressedConfig](#keypressedconfig16)| Yes | Sets the key event consumption configuration. | 193| callback | Callback<[KeyEvent](./js-apis-keyevent.md#keyevent)> | Yes | Callback used to return the key event.| 194 195**Error codes**: 196 197For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 198 199| Error Code | Error Message | 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**Example** 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 225Unsubscribes from key press events. 226 227**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 228 229**Parameters** 230 231| Name | Type | Mandatory | Description | 232| ---------- | -------------------------- | ---- | ---------- | 233| type | string | Yes | Event type. This parameter has a fixed value of **keyPressed**. | 234| callback | Callback<[KeyEvent](./js-apis-keyevent.md#keyevent)> | No | Callback to unregister. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.| 235 236**Error codes**: 237 238For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 239 240| Error Code | Error Message | 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**Example** 246 247```js 248try { 249 // Disable listening for a single callback. 250 inputConsumer.off('keyPressed', (event: KeyEvent) => { 251 console.log(`Unsubscribe success ${JSON.stringify(event)}`); 252 }); 253 // Disable listening for all callbacks. 254 inputConsumer.off("keyPressed"); 255} catch (error) { 256 console.log(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 257} 258``` 259