1# 按键事件 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9按键事件是指组件与键盘、遥控器等按键设备交互时触发的事件，适用于所有可获焦组件，例如Button。对于默认不可获焦的组件，如Text，Image等，可以将focusable属性设置为true后使用按键事件。 10按键事件触发的流程和具体时机参考[按键事件数据流](../../../ui/arkts-interaction-development-guide-keyboard.md#按键事件数据流)。 11 12> **说明：** 13> 14> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15 16## onKeyEvent 17 18onKeyEvent(event: (event: KeyEvent) => void): T 19 20绑定该方法的组件获焦后，按键动作触发该回调。 21 22**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 23 24**系统能力：** SystemCapability.ArkUI.ArkUI.Full 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ------ | ----------------------------- | ---- | ------------------ | 30| event | (event: [KeyEvent](#keyevent对象说明)) => void | 是 | 获得KeyEvent对象。 | 31 32**返回值：** 33 34| 类型 | 说明 | 35| -------- | -------- | 36| T | 返回当前组件。 | 37 38## onKeyEvent<sup>15+</sup> 39onKeyEvent(event: Callback\<KeyEvent, boolean>): T 40 41当绑定该方法的组件获得焦点后，按键操作将触发此回调。若此回调的返回值为`true`，则视为按键事件已被处理。 42 43**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| ------ | ----------------------------- | ---- | ------------------ | 51| event | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent对象说明), boolean> | 是 | 按键事件的回调。 | 52 53**返回值：** 54 55| 类型 | 说明 | 56| -------- | -------- | 57| T | 返回当前组件。 | 58 59## onKeyPreIme<sup>12+</sup> 60 61onKeyPreIme(event: Callback<KeyEvent, boolean>): T 62 63绑定该方法的组件获焦后，按键动作优先触发该回调。 64 65该回调的返回值为`true`时，视作该按键事件已被消费，后续的事件回调（`keyboardShortcut`、输入法事件、`onKeyEvent`）会被拦截，不再触发。 66 67**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 68 69**系统能力：** SystemCapability.ArkUI.ArkUI.Full 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| ------ | ----------------------------- | ---- | ------------------ | 75| event | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent对象说明), boolean> | 是 | 处理按键事件的回调。 | 76 77**返回值：** 78 79| 类型 | 说明 | 80| -------- | -------- | 81| T | 返回当前组件。 | 82 83## onKeyEventDispatch<sup>15+</sup> 84 85onKeyEventDispatch(event: Callback\<KeyEvent, boolean>): T 86 87对应组件收到按键事件时，会触发该回调，该按键事件不会分发给其子组件。不支持构造KeyEvent进行分发，只支持分发已有的按键事件。 88 89该回调的返回值为`true`时，视作该按键事件已被消费，不会[冒泡](../../../ui/arkts-interaction-basic-principles.md#事件冒泡)给父组件处理。 90 91**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ----------------------------- | ---- | ------------------ | 99| event | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent对象说明), boolean> | 是 | 处理按键事件分发的回调。 | 100 101**返回值：** 102 103| 类型 | 说明 | 104| -------- | -------- | 105| T | 返回当前组件。 | 106 107 108## KeyEvent对象说明 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112| 名称 | 类型 | 只读 | 可选 | 说明 | 113| ------------------------------------- | ---------------------------------------- |--------- | ------------- | -------------------------- | 114| type | [KeyType](ts-appendix-enums.md#keytype) | 否 | 否 |按键的类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 115| [keyCode](../../apis-input-kit/js-apis-keycode.md#keycode) | number | 否 | 否 |按键的键码。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 116| keyText | string | 否 | 否 |按键的键值。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 117| keySource | [KeySource](ts-appendix-enums.md#keysource) | 否 | 否 |触发当前按键的输入设备类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 118| deviceId | number | 否 | 否 |触发当前按键的输入设备ID。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 119| metaKey | number | 否 | 否 |按键发生时元键（即键盘左下角紧挨Ctrl键或Fn标记了窗口logo的按键）的状态，1表示按压态，0表示未按压态。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 120| timestamp | number | 否 | 否 |事件时间戳。触发事件时距离系统启动的时间间隔，单位：ns。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 121| stopPropagation | () => void | 否 | 否 |阻塞事件冒泡传递。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 122| intentionCode<sup>10+</sup> | [IntentionCode](#intentioncode10) | 否 | 否 |按键对应的意图。<br/>默认值：IntentionCode.INTENTION_UNKNOWN。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 123| unicode<sup>14+</sup> | number | 否 | 是 |按键的Unicode码值。支持范围为非空格的基本拉丁字符：0x0021-0x007E，不支持字符为0。组合键场景下，返回当前keyEvent对应按键的Unicode码值。 <br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| 124| isNumLockOn<sup>19+</sup> | boolean | 否 | 是 |NumLock是否锁定（true: 锁定；false: 解锁）。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 125| isCapsLockOn<sup>19+</sup> | boolean | 否 | 是 |CapsLock是否锁定（true: 锁定；false: 解锁）。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 126| isScrollLockOn<sup>19+</sup> | boolean | 否 | 是 |ScrollLock是否锁定（true: 锁定；false: 解锁）。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 127 128### getModifierKeyState<sup>12+</sup> 129 130getModifierKeyState?(keys: Array<string>): boolean 131 132获取功能键按压状态。 133 134**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 135 136**系统能力：** SystemCapability.ArkUI.ArkUI.Full 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| ------ | ----------------------------- | ---- | ------------------ | 142| keys | Array<string> | 是 | 获取功能键按压状态。报错信息请参考以下错误码。支持功能键 'Ctrl'\| 'Alt' \| 'Shift'。<br/>**说明：**<br/>此接口不支持在手写笔场景下使用。 | 143 144**返回值：** 145 146| 类型 | 说明 | 147| ------- | ----------------------------------------------------- | 148| boolean | 功能键是否被按下。true表示被按下，false表示未被按下。 | 149 150**错误码**： 151 152以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 153 154| 错误码ID | 错误信息 | 155| ------- | -------- | 156| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 157 158## IntentionCode<sup>10+</sup> 159 160type IntentionCode = IntentionCode 161 162按键对应的意图。 163 164**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 165 166**系统能力：** SystemCapability.ArkUI.ArkUI.Full 167 168| 类型 | 说明 | 169| ----- | ----------------- | 170| [IntentionCode](../../apis-input-kit/js-apis-intentioncode.md) | 按键对应的意图。| 171 172## 示例 173 174### 示例1（触发onKeyEvent回调） 175 176该示例通过按钮设置了按键事件。按钮获焦时，按下按键可触发onKeyEvent回调。按键事件触发的流程和具体时机参考[按键事件数据流](../../../ui/arkts-interaction-development-guide-keyboard.md#按键事件数据流)。 177 178```ts 179// xxx.ets 180@Entry 181@Component 182struct KeyEventExample { 183 @State text: string = '' 184 @State eventType: string = '' 185 186 build() { 187 Column() { 188 Button('KeyEvent') 189 .defaultFocus(true) 190 .onKeyEvent((event?: KeyEvent) => { 191 if(event){ 192 if (event.type === KeyType.Down) { 193 this.eventType = 'Down' 194 } 195 if (event.type === KeyType.Up) { 196 this.eventType = 'Up' 197 } 198 this.text = 'KeyType:' + this.eventType + '\nkeyCode:' + event.keyCode + '\nkeyText:' + event.keyText + '\nintentionCode:' + event.intentionCode 199 } 200 }) 201 Text(this.text).padding(15) 202 }.height(300).width('100%').padding(35) 203 } 204} 205``` 206 207  208 209### 示例2（获取Unicode码值） 210 211该示例通过按键事件获取所按按键的Unicode码值。 212 213```ts 214// xxx.ets 215@Entry 216@Component 217struct KeyEventExample { 218 @State text: string = '' 219 @State eventType: string = '' 220 @State keyType: string = '' 221 222 build() { 223 Column({ space: 10 }) { 224 Button('KeyEvent') 225 .onKeyEvent((event?: KeyEvent) => { 226 if(event){ 227 if (event.type === KeyType.Down) { 228 this.eventType = 'Down' 229 } 230 if (event.type === KeyType.Up) { 231 this.eventType = 'Up' 232 } 233 if (event.unicode == 97) { 234 this.keyType = 'a' 235 } else if (event.unicode == 65) { 236 this.keyType = 'A' 237 } else { 238 this.keyType = ' ' 239 } 240 this.text = 'KeyType:' + this.eventType + '\nUnicode:' + event.unicode + '\nkeyCode:' + event.keyCode + '\nkeyType:' + this.keyType 241 } 242 }) 243 Text(this.text).padding(15) 244 }.height(300).width('100%').padding(35) 245 } 246} 247``` 248 249 250 251### 示例3（触发onKeyPreIme回调） 252 253该示例使用onKeyPreIme屏蔽输入框中的方向左键。 254 255```ts 256import { KeyCode } from '@kit.InputKit'; 257 258@Entry 259@Component 260struct PreImeEventExample { 261 @State buttonText: string = ''; 262 @State buttonType: string = ''; 263 @State columnText: string = ''; 264 @State columnType: string = ''; 265 266 build() { 267 Column() { 268 Search({ 269 placeholder: "Search..." 270 }) 271 .width("80%") 272 .height("40vp") 273 .border({ radius:"20vp" }) 274 .onKeyPreIme((event:KeyEvent) => { 275 // 使用方向左键不生效 276 if (event.keyCode == KeyCode.KEYCODE_DPAD_LEFT) { 277 return true; 278 } 279 return false; 280 }) 281 } 282 } 283} 284``` 285 286### 示例4（使用stopPropagation阻止冒泡） 287 288该示例使用stopPropagation阻止事件冒泡。即，通过在Button的onKeyEvent回调中加入event.stopPropagation()方法，达到“仅Button响应键盘事件，Column不响应”的效果。 289 290>**说明：** 291> 292> 1. onKeyEvent事件默认是冒泡的。 293> 2. 事件冒泡：在一个树形结构中，当子节点处理完一个事件后，再将该事件交给它的父节点处理。 294> 3. 可以在[onKeyEvent<sup>15+</sup>](#onkeyevent15)中，通过返回true消费按键事件阻止冒泡，效果等同于stopPropagation。 295 296```ts 297@Entry 298@Component 299struct KeyEventExample { 300 @State buttonText: string = ''; 301 @State buttonType: string = ''; 302 @State columnText: string = ''; 303 @State columnType: string = ''; 304 305 build() { 306 Column() { 307 Button('onKeyEvent') 308 .defaultFocus(true) 309 .width(140).height(70) 310 .onKeyEvent((event?: KeyEvent) => { 311 // 通过stopPropagation阻止事件冒泡 312 if(event){ 313 if(event.stopPropagation){ 314 event.stopPropagation(); 315 } 316 if (event.type === KeyType.Down) { 317 this.buttonType = 'Down'; 318 } 319 if (event.type === KeyType.Up) { 320 this.buttonType = 'Up'; 321 } 322 this.buttonText = 'Button: \n' + 323 'KeyType:' + this.buttonType + '\n' + 324 'KeyCode:' + event.keyCode + '\n' + 325 'KeyText:' + event.keyText; 326 } 327 }) 328 329 Divider() 330 Text(this.buttonText).fontColor(Color.Green) 331 332 Divider() 333 Text(this.columnText).fontColor(Color.Red) 334 }.width('100%').height('100%').justifyContent(FlexAlign.Center) 335 .onKeyEvent((event?: KeyEvent) => { // 给父组件Column设置onKeyEvent事件 336 if(event){ 337 if (event.type === KeyType.Down) { 338 this.columnType = 'Down'; 339 } 340 if (event.type === KeyType.Up) { 341 this.columnType = 'Up'; 342 } 343 this.columnText = 'Column: \n' + 344 'KeyType:' + this.columnType + '\n' + 345 'KeyCode:' + event.keyCode + '\n' + 346 'KeyText:' + event.keyText; 347 } 348 }) 349 } 350} 351```
