按键事件

按键事件指组件与键盘、遥控器等按键设备交互时触发的事件，适用于所有可获焦组件，例如Button。对于Text，Image等默认不可获焦的组件，可以设置focusable属性为true后使用按键事件。 按键事件触发的流程和具体时机参考按键事件数据流。

说明：

从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

onKeyEvent

onKeyEvent(event: (event: KeyEvent) => void): T

绑定该方法的组件获焦后，按键动作触发该回调。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	KeyEvent	是	获得KeyEvent对象。

返回值：

类型	说明
T	返回当前组件。

onKeyEvent¹⁵⁺

onKeyEvent(event: Callback<KeyEvent, boolean>): T

当绑定该方法的组件获得焦点后，按键操作将触发此回调。若此回调的返回值为true，则视为按键事件已被处理。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	Callback<KeyEvent, boolean>	是	按键事件的回调。

返回值：

类型	说明
T	返回当前组件。

onKeyPreIme¹²⁺

onKeyPreIme(event: Callback<KeyEvent, boolean>): T

绑定该方法的组件获焦后，按键动作优先触发该回调。

该回调的返回值为true时，视作该按键事件已被消费，后续的事件回调（keyboardShortcut、输入法事件、onKeyEvent）会被拦截，不再触发。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	Callback<KeyEvent, boolean>	是	处理按键事件的回调。

返回值：

类型	说明
T	返回当前组件。

onKeyEventDispatch¹⁵⁺

onKeyEventDispatch(event: Callback<KeyEvent, boolean>): T

对应组件收到按键事件时，会触发该回调，该按键事件不会分发给其子组件。不支持构造KeyEvent进行分发，只支持分发已有的按键事件。

该回调的返回值为true时，视作该按键事件已被消费，不会冒泡给父组件处理。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	Callback<KeyEvent, boolean>	是	处理按键事件分发的回调。

返回值：

类型	说明
T	返回当前组件。

KeyEvent对象说明

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	描述
type	KeyType	按键的类型。
keyCode	number	按键的键码。
keyText	string	按键的键值。
keySource	KeySource	触发当前按键的输入设备类型。
deviceId	number	触发当前按键的输入设备ID。
metaKey	number	按键发生时元键（即键盘左下角紧挨Ctrl键，或Fn标记了窗口logo的按键）的状态，1表示按压态，0表示未按压态。
timestamp	number	事件时间戳。触发事件时距离系统启动的时间间隔，单位：ns。
stopPropagation	() => void	阻塞事件冒泡传递。
intentionCode10+	IntentionCode	按键对应的意图。
getModifierKeyState12+	(Array<string>) => bool	获取功能键按压状态。报错信息请参考以下错误码。支持功能键 'Ctrl'|'Alt'|'Shift'|'Fn'，设备外接带Fn键的键盘不支持Fn键查询。 原子化服务API： 从API version 13开始，该接口支持在原子化服务中使用。
unicode14+	number	按键的unicode码值。支持范围为非空格的基本拉丁字符：0x0021-0x007E，不支持字符为0。组合键场景下，返回当前keyEvent对应按键的unicode码值。 原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed.

示例

示例1（触发onKeyEvent回调）

该示例通过按钮设置了按键事件，按钮获焦时可触发onKeyEvent回调。

// xxx.ets
@Entry
@Component
struct KeyEventExample {
  @State text: string = ''
  @State eventType: string = ''

  build() {
    Column() {
      Button('KeyEvent')
        .onKeyEvent((event?: KeyEvent) => {
          if(event){
            if (event.type === KeyType.Down) {
              this.eventType = 'Down'
            }
            if (event.type === KeyType.Up) {
              this.eventType = 'Up'
            }
            this.text = 'KeyType:' + this.eventType + '\nkeyCode:' + event.keyCode + '\nkeyText:' + event.keyText + '\nintentionCode:' + event.intentionCode
          }
        })
      Text(this.text).padding(15)
    }.height(300).width('100%').padding(35)
  }
}

示例2（获取uniCode码值）

该示例通过key事件获取到所按按键的unicode码值。

// xxx.ets
@Entry
@Component
struct KeyEventExample {
  @State text: string = ''
  @State eventType: string = ''
  @State keyType: string = ''

  build() {
    Column({ space: 10 }) {
      Button('KeyEvent')
        .onKeyEvent((event?: KeyEvent) => {
          if(event){
            if (event.type === KeyType.Down) {
              this.eventType = 'Down'
            }
            if (event.type === KeyType.Up) {
              this.eventType = 'Up'
            }
            if (event.unicode == 97) {
              this.keyType = 'a'
            } else if (event.unicode == 65) {
              this.keyType = 'A'
            } else {
              this.keyType = ' '
            }
            this.text = 'KeyType:' + this.eventType + '\nUnicode:' + event.unicode + '\nkeyCode:' + event.keyCode + '\nkeyType:' + this.keyType
          }
        })
      Text(this.text).padding(15)
    }.height(300).width('100%').padding(35)
  }
}

示例3（触发onKeyPreIme回调）

该示例使用onKeyPreIme屏蔽在输入框中使用方向左键。

import { KeyCode } from '@kit.InputKit';

@Entry
@Component
struct PreImeEventExample {
  @State buttonText: string = '';
  @State buttonType: string = '';
  @State columnText: string = '';
  @State columnType: string = '';

  build() {
    Column() {
      Search({
        placeholder: "Search..."
      })
        .width("80%")
        .height("40vp")
        .border({ radius:"20vp" })
        .onKeyPreIme((event:KeyEvent) => {
          // 使用方向左键不生效
          if (event.keyCode == KeyCode.KEYCODE_DPAD_LEFT) {
            return true;
          }
          return false;
        })
    }
  }
}