1# @ohos.multimodalInput.inputConsumer (全局快捷键)(系统接口) 2 3<!--Kit: Input Kit--> 4<!--Subsystem: MultimodalInput--> 5<!--Owner: @zhaoxueyuan--> 6<!--Designer: @hanruofei--> 7<!--Tester: @Lyuxin--> 8<!--Adviser: @Brilliantry_Rui--> 9 10全局快捷键订阅模块，用于处理组合按键的订阅。 11 12> **说明：** 13> 14> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 16> - 本模块接口为系统接口。 17> 18> - 本模块接口仅对系统快捷键生效，系统快捷键指系统定义的全局快捷键。 19 20 21## 导入模块 22 23```js 24import { inputConsumer } from '@kit.InputKit'; 25``` 26 27## inputConsumer.on 28 29on(type: 'key', keyOptions: KeyOptions, callback: Callback<KeyOptions>): void 30 31订阅系统快捷键，当满足条件的组合按键输入事件发生时，使用Callback异步方式上报组合按键数据。 32 33**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| ---------- | -------------------------- | ---- | ---------------------------------------- | 39| type | string | 是 | 事件类型，目前仅支持'key'。 | 40| keyOptions | [KeyOptions](#keyoptions) | 是 | 组合键选项。 | 41| callback | Callback<KeyOptions> | 是 | 回调函数，当满足条件的组合按键输入事件发生时，异步上报组合按键数据。 | 42 43**示例：** 44 45```js 46import { inputConsumer } from '@kit.InputKit'; 47 48@Entry 49@Component 50struct Index { 51 build() { 52 RelativeContainer() { 53 Text() 54 .onClick(() => { 55 let leftAltKey = 2045; 56 let tabKey = 2049; 57 let keyOptions: inputConsumer.KeyOptions = { 58 preKeys: [ leftAltKey ], 59 finalKey: tabKey, 60 isFinalKeyDown: true, 61 finalKeyDownDuration: 0 62 }; 63 let callback = (keyOptions: inputConsumer.KeyOptions) => { 64 console.log(`keyOptions: ${JSON.stringify(keyOptions)}`); 65 } 66 try { 67 inputConsumer.on("key", keyOptions, callback); 68 } catch (error) { 69 console.error(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 70 } 71 }) 72 } 73 } 74} 75``` 76 77 78## inputConsumer.off 79 80off(type: 'key', keyOptions: KeyOptions, callback?: Callback<KeyOptions>): void 81 82取消订阅系统快捷键。 83 84**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| ---------- | -------------------------- | ---- | ------------------------------- | 90| type | string | 是 | 事件类型，当前仅支持 'key'。 | 91| keyOptions | [KeyOptions](#keyoptions) | 是 | 组合键选项。 | 92| callback | Callback<KeyOptions> | 否 | 需要取消订阅的回调函数。若不填，则取消当前应用组合键选项已订阅的所有回调函数。 | 93 94**示例：** 95 96```js 97import { inputConsumer } from '@kit.InputKit'; 98 99@Entry 100@Component 101struct Index { 102 build() { 103 RelativeContainer() { 104 Text() 105 .onClick(() => { 106 let leftAltKey = 2045; 107 let tabKey = 2049; 108 // 取消订阅单个回调函数 109 let callback = (keyOptions: inputConsumer.KeyOptions) => { 110 console.log(`keyOptions: ${JSON.stringify(keyOptions)}`); 111 } 112 let keyOption: inputConsumer.KeyOptions = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0}; 113 try { 114 inputConsumer.on("key", keyOption, callback); 115 inputConsumer.off("key", keyOption, callback); 116 console.log(`Unsubscribe success`); 117 } catch (error) { 118 console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 119 } 120 }) 121 } 122 } 123} 124``` 125```js 126import { inputConsumer } from '@kit.InputKit'; 127 128@Entry 129@Component 130struct Index { 131 build() { 132 RelativeContainer() { 133 Text() 134 .onClick(() => { 135 let leftAltKey = 2045; 136 let tabKey = 2049; 137 // 取消订阅所有回调函数 138 let callback = (keyOptions: inputConsumer.KeyOptions) => { 139 console.log(`keyOptions: ${JSON.stringify(keyOptions)}`); 140 } 141 let keyOption: inputConsumer.KeyOptions = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0}; 142 try { 143 inputConsumer.on("key", keyOption, callback); 144 inputConsumer.off("key", keyOption); 145 console.log(`Unsubscribe success`); 146 } catch (error) { 147 console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 148 } 149 }) 150 } 151 } 152} 153``` 154 155## inputConsumer.setShieldStatus<sup>11+</sup> 156 157setShieldStatus(shieldMode: ShieldMode, isShield: boolean): void 158 159设置系统快捷键屏蔽类型。 160 161**需要权限**: ohos.permission.INPUT_CONTROL_DISPATCHING 162 163**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 164 165**参数：** 166 167| 参数名 | 类型 | 必填 | 说明 | 168| ---------- | -------------------------- | ---- | ---------------------------------------- | 169| shieldMode | [ShieldMode](js-apis-inputconsumer-sys.md#shieldmode11) | 是 | 系统快捷键屏蔽类型，目前仅支持取值为'FACTORY_MODE'，表示屏蔽所有系统快捷键。 | 170| isShield | boolean | 是 | 屏蔽类型生效状态，true代表屏蔽类型生效，flase代表不生效。 | 171 172**示例：** 173 174```js 175import { inputConsumer } from '@kit.InputKit'; 176 177@Entry 178@Component 179struct Index { 180 build() { 181 RelativeContainer() { 182 Text() 183 .onClick(() => { 184 let FACTORY_MODE = 0; 185 try { 186 inputConsumer.setShieldStatus(FACTORY_MODE,true); 187 console.log(`set shield status success`); 188 } catch (error) { 189 console.error(`set shield status failed, error: ${JSON.stringify(error, [`code`, `message`])}`); 190 } 191 }) 192 } 193 } 194} 195``` 196 197## inputConsumer.getShieldStatus<sup>11+</sup> 198 199getShieldStatus(shieldMode: ShieldMode): boolean 200 201获取系统快捷键屏蔽类型。 202 203**需要权限**: ohos.permission.INPUT_CONTROL_DISPATCHING 204 205**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 206 207**参数：** 208 209| 参数名 | 类型 | 必填 | 说明 | 210| ---------- | -------------------------- | ---- | ---------------------------------------- | 211| shieldMode | [ShieldMode](js-apis-inputconsumer-sys.md#shieldmode11) | 是 | 系统快捷键屏蔽类型，目前仅支持取值为'FACTORY_MODE'，表示屏蔽所有系统快捷键。 | 212 213**返回值：** 214 215| 类型 | 说明 | 216| ---------- | ---------------------------------------- | 217| boolean | 屏蔽类型生效状态，true代表屏蔽类型生效，flase代表不生效。 | 218 219**示例：** 220 221```js 222import { inputConsumer } from '@kit.InputKit'; 223 224@Entry 225@Component 226struct Index { 227 build() { 228 RelativeContainer() { 229 Text() 230 .onClick(() => { 231 try { 232 let FACTORY_MODE = 0; 233 let shieldstatusResult:Boolean = inputConsumer.getShieldStatus(FACTORY_MODE); 234 console.log(` get shield status result:${JSON.stringify(shieldstatusResult)}`); 235 } catch (error) { 236 console.error(`Failed to get shield status, error: ${JSON.stringify(error, [`code`, `message`])}`); 237 } 238 }) 239 } 240 } 241} 242``` 243 244## KeyOptions 245 246快捷键选项。 247 248**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 249 250| 名称 | 类型 | 只读 | 可选 | 说明 | 251| --------- | ------ | ---- | ---- | ------- | 252| preKeys | Array\<number> | 否 | 否 | 前置按键集合，数量范围[0, 4]，前置按键无顺序要求。<br>如组合按键Ctrl+Alt+A中，Ctrl+Alt称为前置按键。 | 253| finalKey | number | 否 | 否 | 最终按键，此项必填，最终按键触发上报回调函数。<br>如组合按键Ctrl+Alt+A中，A称为最终按键按键。 | 254| isFinalKeyDown | boolean | 否 | 否 | 最终按键状态。<br>ture表示按键按下，false表示按键抬起。 | 255| finalKeyDownDuration | number | 否 | 否 | 最终按键保持按下持续时间，单位：μs。<br>当finalKeyDownDuration为0时，立即触发回调函数。<br>当finalKeyDownDuration大于0时，isFinalKeyDown为true，则最终按键按下超过设置时长后触发回调函数；isFinalKeyDown为false，则最终按键按下到抬起时间小于设置时长时触发回调函数。 | 256| isRepeat<sup>18+</sup> | boolean | 否 | 否 | 是否上报重复的按键事件。true表示上报，false表示不上报，若不填默认为true。 | 257 258## shieldMode<sup>11+</sup> 259 260系统快捷键屏蔽类型。 261 262**系统能力：** SystemCapability.MultimodalInput.Input.InputConsumer 263 264| 名称 | 值 | 说明 | 265| ------------------------------ | ----------- | ---------------- | 266| UNSET_MODE | -1 | 值为-1，表示不屏蔽系统快捷键。 | 267| FACTORY_MODE | 0 | 值为0，表示屏蔽所有系统快捷键。 | 268| OOBE_MODE | 1 | 值为1，表示OOBE阶段屏蔽所有系统快捷键，暂不支持该能力。 |