1# @ohos.multimodalInput.inputConsumer (Global Shortcut Keys) 2 3The **inputConsumer** module implements listening for combination key events as well as listening and interception for volume 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> - Global shortcut keys are combination keys defined by the system or application. System shortcut keys are defined by the system, and application shortcut keys are defined by applications. 10 11 12## Modules to Import 13 14 15```js 16import { inputConsumer, KeyEvent } from '@kit.InputKit'; 17``` 18 19## HotkeyOptions 20 21Defines shortcut key options. 22 23**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 24 25| Name | Type | Read-Only | Optional | Description | 26| --------- | ------ | ------- | ------- | ------- | 27| preKeys | Array<number> | No | 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.| 28| finalKey | number | No | No | Modified key, which can be any key except the modifier keys and Meta key. For details about the keys, see [Keycode](js-apis-keycode.md).<br>For example, in **Ctrl+Shift+Esc**, **Esc** is the modified key.| 29| isRepeat | boolean | No | Yes | 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**.| 30 31## KeyPressedConfig<sup>16+</sup> 32 33Sets the key event consumption configuration. 34 35**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 36 37| Name | Type | Read-Only | Optional | Description | 38| --------- | ------ | ------- | ------- | ------- | 39| key | number | No | 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.| 40| action | number | No | No | Key event type. Currently, this parameter can only be set to **1**, indicating key press.| 41| isRepeat | boolean | No | 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**.| 42 43## inputConsumer.getAllSystemHotkeys 44 45getAllSystemHotkeys(): Promise<Array<HotkeyOptions>> 46 47Obtains all system shortcut keys. This API uses a promise to return the result. 48 49**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 50 51**Return value** 52 53| Type | Description | 54| ---------- | ---------------------------------------- | 55| Promise<Array<HotkeyOptions>> | Promise used to return the list of all system shortcut keys.| 56 57**Error codes**: 58 59For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 60 61| Error Code| Error Message | 62| -------- | ------------------------- | 63| 801 | Capability not supported. | 64 65**Example** 66 67```js 68inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => { 69 console.log(`List of system hotkeys : ${JSON.stringify(data)}`); 70}); 71``` 72 73## inputConsumer.on('hotkeyChange') 74 75on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void 76 77Subscribes to application shortcut key change events based on the specified options. This API uses an asynchronous callback to return the result. 78 79**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 80 81**Parameters** 82 83| Name | Type | Mandatory | Description | 84| ---------- | -------------------------- | ---- | ---------- | 85| type | string | Yes | Event type. This parameter has a fixed value of **hotkeyChange**. | 86| hotkeyOptions | [HotkeyOptions](#hotkeyoptions) | Yes | Shortcut key options. | 87| callback | Callback<HotkeyOptions> | Yes | Callback used to return the application shortcut key change event.| 88 89**Error codes**: 90 91For details about the error codes, see [Global Shortcut Key Error Codes](errorcode-inputconsumer.md) and [Universal Error Codes](../errorcode-universal.md). 92 93| Error Code | Error Message | 94| ---- | --------------------- | 95| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 96| 801 | Capability not supported. | 97| 4200002 | The hotkey has been used by the system. | 98| 4200003 | The hotkey has been subscribed to by another. | 99 100**Example** 101 102```js 103let leftCtrlKey = 2072; 104let zKey = 2042; 105let hotkeyOptions: inputConsumer.HotkeyOptions = { 106 preKeys: [ leftCtrlKey ], 107 finalKey: zKey, 108 isRepeat: true 109}; 110let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => { 111 console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`); 112} 113try { 114 inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback); 115} catch (error) { 116 console.error(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 117} 118``` 119 120## inputConsumer.off('hotkeyChange') 121 122off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void 123 124Unsubscribes from application shortcut key change events. 125 126**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 127 128**Parameters** 129 130| Name | Type | Mandatory | Description | 131| ---------- | -------------------------- | ---- | ---------- | 132| type | string | Yes | Event type. This parameter has a fixed value of **hotkeyChange**. | 133| hotkeyOptions | [HotkeyOptions](#hotkeyoptions) | Yes | Shortcut key options. | 134| callback | Callback<HotkeyOptions> | No | Callback to unregister. If this parameter is left unspecified, listening will be disabled for all callbacks registered for the specified shortcut key options.| 135 136**Error codes**: 137 138For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 139 140| Error Code | Error Message | 141| ---- | --------------------- | 142| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 143| 801 | Capability not supported. | 144 145**Example** 146 147```js 148let leftCtrlKey = 2072; 149let zKey = 2042; 150// Disable listening for a single callback. 151let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => { 152 console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`); 153} 154let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true}; 155try { 156 inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback); 157 inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback); 158 console.log(`Unsubscribe success`); 159} catch (error) { 160 console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 161} 162``` 163 164```js 165let leftCtrlKey = 2072; 166let zKey = 2042; 167// Disable listening for all callbacks. 168let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => { 169 console.log(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`); 170} 171let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true}; 172try { 173 inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback); 174 inputConsumer.off("hotkeyChange", hotkeyOption); 175 console.log(`Unsubscribe success`); 176} catch (error) { 177 console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 178} 179``` 180 181## inputConsumer.on('keyPressed')<sup>16+</sup> 182 183on(type: 'keyPressed', options: KeyPressedConfig, callback: Callback<KeyEvent>): void 184 185Subscribes to key press events. This API uses an asynchronous callback to return the result. If the current application is in the foreground focus window, a callback is triggered when the specified key is pressed. This API is available only for mobile phones and tablets. 186 187If the API call is successful, the system's default response to the key event will be intercepted; that is, system-level actions, such as volume adjustment, will no longer be triggered. To restore the system response, call [off](#inputconsumeroffkeypressed16) to disable listening for the key event. 188 189**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 190 191**Parameters** 192 193| Name | Type | Mandatory | Description | 194| ---------- | -------------------------- | ---- | ---------- | 195| type | string | Yes | Event type. This parameter has a fixed value of **keyPressed**. | 196| options | [KeyPressedConfig](#keypressedconfig16)| Yes | Sets the key event consumption configuration. | 197| callback | Callback<[KeyEvent](./js-apis-keyevent.md#keyevent)> | Yes | Callback used to return key press events.| 198 199**Error codes**: 200 201For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 202 203| Error Code | Error Message | 204| ---- | --------------------- | 205| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 206| 801 | Capability not supported. | 207 208**Example** 209 210```js 211try { 212 let options: inputConsumer.KeyPressedConfig = { 213 key: 16, 214 action: 1, 215 isRepeat: false, 216 } 217 inputConsumer.on('keyPressed', options, (event: KeyEvent) => { 218 console.log(`Subscribe success ${JSON.stringify(event)}`); 219 }); 220} catch (error) { 221 console.error(`Subscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 222} 223``` 224 225## inputConsumer.off('keyPressed')<sup>16+</sup> 226 227off(type: 'keyPressed', callback?: Callback<KeyEvent>): void 228 229Disables listening for the **keyPressed** event. This API uses an asynchronous callback to return the result. If the API call is successful, the system's default response to the key event will be resumed; that is, system-level actions, such as volume adjustment, will be triggered normally. This API is available only for mobile phones and tablets. 230 231**System capability**: SystemCapability.MultimodalInput.Input.InputConsumer 232 233**Parameters** 234 235| Name | Type | Mandatory | Description | 236| ---------- | -------------------------- | ---- | ---------- | 237| type | string | Yes | Event type. This parameter has a fixed value of **keyPressed**. | 238| callback | Callback<[KeyEvent](./js-apis-keyevent.md#keyevent)> | No | Callback to unregister. If this parameter is not specified, listening will be disabled for all registered callbacks.| 239 240**Error codes**: 241 242For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 243 244| Error Code | Error Message | 245| ---- | --------------------- | 246| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 247| 801 | Capability not supported. | 248 249**Example** 250 251```js 252try { 253 // Disable listening for a single callback. 254 inputConsumer.off('keyPressed', (event: KeyEvent) => { 255 console.log(`Unsubscribe success ${JSON.stringify(event)}`); 256 }); 257 // Disable listening for all callbacks. 258 inputConsumer.off("keyPressed"); 259} catch (error) { 260 console.error(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 261} 262``` 263