1# 按键事件 2 3按键事件指组件与键盘、遥控器等按键设备交互时触发的事件，适用于所有可获焦组件，例如Button。对于Text，Image等默认不可获焦的组件，可以设置focusable属性为true后使用按键事件。 4按键事件触发的流程和具体时机参考[按键事件数据流](../../../ui/arkts-common-events-device-input-event.md#按键事件数据流)。 5 6> **说明：** 7> 8> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 9 10## onKeyEvent 11 12onKeyEvent(event: (event: KeyEvent) => void): T 13 14绑定该方法的组件获焦后，按键动作触发该回调。 15 16**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 17 18**系统能力：** SystemCapability.ArkUI.ArkUI.Full 19 20**参数：** 21 22| 参数名 | 类型 | 必填 | 说明 | 23| ------ | ----------------------------- | ---- | ------------------ | 24| event | [KeyEvent](#keyevent对象说明) | 是 | 获得KeyEvent对象。 | 25 26**返回值：** 27 28| 类型 | 说明 | 29| -------- | -------- | 30| T | 返回当前组件。 | 31 32## onKeyPreIme<sup>12+</sup> 33 34onKeyPreIme(event: Callback<KeyEvent, boolean>): T 35 36绑定该方法的组件获焦后，按键动作优先触发该回调。 37 38该回调的返回值为`true`时，视作该按键事件已被消费，后续的事件回调（`keyboardShortcut`、输入法事件、`onKeyEvent`）会被拦截，不再触发。 39 40**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 41 42**系统能力：** SystemCapability.ArkUI.ArkUI.Full 43 44**参数：** 45 46| 参数名 | 类型 | 必填 | 说明 | 47| ------ | ----------------------------- | ---- | ------------------ | 48| event | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent对象说明), boolean> | 是 | 处理按键事件的回调。 | 49 50**返回值：** 51 52| 类型 | 说明 | 53| -------- | -------- | 54| T | 返回当前组件。 | 55 56## KeyEvent对象说明 57 58**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 59 60**系统能力：** SystemCapability.ArkUI.ArkUI.Full 61 62| 名称 | 类型 | 描述 | 63| ------------------------------------- | ---------------------------------------- | -------------------------- | 64| type | [KeyType](ts-appendix-enums.md#keytype) | 按键的类型。 | 65| [keyCode](../../apis-input-kit/js-apis-keycode.md#keycode) | number | 按键的键码。 | 66| keyText | string | 按键的键值。 | 67| keySource | [KeySource](ts-appendix-enums.md#keysource) | 触发当前按键的输入设备类型。 | 68| deviceId | number | 触发当前按键的输入设备ID。 | 69| metaKey | number | 按键发生时元键（即Windows键盘的WIN键、Mac键盘的Command键）的状态，1表示按压态，0表示未按压态。 | 70| timestamp | number | 事件时间戳。触发事件时距离系统启动的时间间隔，单位：ns。 | 71| stopPropagation | () => void | 阻塞事件冒泡传递。 | 72| intentionCode<sup>10+</sup> | [IntentionCode](../../apis-input-kit/js-apis-intentioncode.md) | 按键对应的意图。 | 73| getModifierKeyState<sup>12+</sup> | (Array<string>) => bool | 获取功能键按压状态。报错信息请参考以下错误码。支持功能键 'Ctrl'\|'Alt'\|'Shift'\|'Fn'，设备外接带Fn键的键盘不支持Fn键查询。 <br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。| 74 75**错误码**： 76 77以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 78 79| 错误码ID | 错误信息 | 80| ------- | -------- | 81| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 82 83## 示例 84 85```ts 86// xxx.ets 87@Entry 88@Component 89struct KeyEventExample { 90 @State text: string = '' 91 @State eventType: string = '' 92 93 build() { 94 Column() { 95 Button('KeyEvent') 96 .onKeyEvent((event?: KeyEvent) => { 97 if(event){ 98 if (event.type === KeyType.Down) { 99 this.eventType = 'Down' 100 } 101 if (event.type === KeyType.Up) { 102 this.eventType = 'Up' 103 } 104 this.text = 'KeyType:' + this.eventType + '\nkeyCode:' + event.keyCode + '\nkeyText:' + event.keyText + '\nintentionCode:' + event.intentionCode 105 } 106 }) 107 Text(this.text).padding(15) 108 }.height(300).width('100%').padding(35) 109 } 110} 111``` 112 113  114
