• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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## onKeyEvent<sup>15+</sup>
33onKeyEvent(event: Callback\<KeyEvent, boolean>): T
34
35当绑定该方法的组件获得焦点后，按键操作将触发此回调。若此回调的返回值为`true`，则视为按键事件已被处理。
36
37**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。
38
39**系统能力：** SystemCapability.ArkUI.ArkUI.Full
40
41**参数：**
42
43| 参数名 | 类型                          | 必填 | 说明               |
44| ------ | ----------------------------- | ---- | ------------------ |
45| event  | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent对象说明), boolean> | 是   | 按键事件的回调。 |
46
47**返回值：**
48
49| 类型 | 说明 |
50| -------- | -------- |
51| T | 返回当前组件。 |
52
53## onKeyPreIme<sup>12+</sup>
54
55onKeyPreIme(event: Callback<KeyEvent, boolean>): T
56
57绑定该方法的组件获焦后，按键动作优先触发该回调。
58
59该回调的返回值为`true`时，视作该按键事件已被消费，后续的事件回调（`keyboardShortcut`、输入法事件、`onKeyEvent`）会被拦截，不再触发。
60
61**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
62
63**系统能力：** SystemCapability.ArkUI.ArkUI.Full
64
65**参数：**
66
67| 参数名 | 类型                          | 必填 | 说明               |
68| ------ | ----------------------------- | ---- | ------------------ |
69| event  | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent对象说明), boolean> | 是   | 处理按键事件的回调。 |
70
71**返回值：**
72
73| 类型 | 说明 |
74| -------- | -------- |
75| T | 返回当前组件。 |
76
77## onKeyEventDispatch<sup>15+</sup>
78
79onKeyEventDispatch(event: Callback\<KeyEvent, boolean>): T
80
81对应组件收到按键事件时，会触发该回调，该按键事件不会分发给其子组件。不支持构造KeyEvent进行分发，只支持分发已有的按键事件。
82
83该回调的返回值为`true`时，视作该按键事件已被消费，不会冒泡给父组件处理。
84
85**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。
86
87**系统能力：** SystemCapability.ArkUI.ArkUI.Full
88
89**参数：**
90
91| 参数名 | 类型                          | 必填 | 说明               |
92| ------ | ----------------------------- | ---- | ------------------ |
93| event  | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent对象说明), boolean> | 是   | 处理按键事件分发的回调。 |
94
95**返回值：**
96
97| 类型 | 说明 |
98| -------- | -------- |
99| T | 返回当前组件。 |
100
101
102## KeyEvent对象说明
103
104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
105
106**系统能力：** SystemCapability.ArkUI.ArkUI.Full
107
108| 名称                                    | 类型                                       | 描述                         |
109| ------------------------------------- | ---------------------------------------- | -------------------------- |
110| type                                  | [KeyType](ts-appendix-enums.md#keytype)  | 按键的类型。                     |
111| [keyCode](../../apis-input-kit/js-apis-keycode.md#keycode) | number                                   | 按键的键码。                     |
112| keyText                               | string                                   | 按键的键值。                     |
113| keySource                             | [KeySource](ts-appendix-enums.md#keysource) | 触发当前按键的输入设备类型。             |
114| deviceId                              | number                                   | 触发当前按键的输入设备ID。             |
115| metaKey                               | number                                   | 按键发生时元键（即键盘左下角紧挨Ctrl键，或Fn标记了窗口logo的按键）的状态，1表示按压态，0表示未按压态。 |
116| timestamp                             | number                                   | 事件时间戳。触发事件时距离系统启动的时间间隔，单位：ns。 |
117| stopPropagation                       | () => void                               | 阻塞事件冒泡传递。                  |
118| intentionCode<sup>10+</sup>           | [IntentionCode](../../apis-input-kit/js-apis-intentioncode.md) | 按键对应的意图。       |
119| getModifierKeyState<sup>12+</sup> | (Array&lt;string&gt;) => bool | 获取功能键按压状态。报错信息请参考以下错误码。支持功能键 'Ctrl'\|'Alt'\|'Shift'\|'Fn'，设备外接带Fn键的键盘不支持Fn键查询。 <br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。|
120| unicode<sup>14+</sup>                              | number                                   | 按键的unicode码值。支持范围为非空格的基本拉丁字符：0x0021-0x007E，不支持字符为0。组合键场景下，返回当前keyEvent对应按键的unicode码值。 <br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。|
121
122**错误码**：
123
124以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。
125
126| 错误码ID | 错误信息 |
127| ------- | -------- |
128| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. |
129
130## 示例
131
132### 示例1（触发onKeyEvent回调）
133
134该示例通过按钮设置了按键事件，按钮获焦时按下按键可触发onKeyEvent回调，按键事件触发的流程和具体时机参考[按键事件数据流](../../../ui/arkts-common-events-device-input-event.md#按键事件数据流)。
135
136```ts
137// xxx.ets
138@Entry
139@Component
140struct KeyEventExample {
141  @State text: string = ''
142  @State eventType: string = ''
143
144  build() {
145    Column() {
146      Button('KeyEvent')
147        .onKeyEvent((event?: KeyEvent) => {
148          if(event){
149            if (event.type === KeyType.Down) {
150              this.eventType = 'Down'
151            }
152            if (event.type === KeyType.Up) {
153              this.eventType = 'Up'
154            }
155            this.text = 'KeyType:' + this.eventType + '\nkeyCode:' + event.keyCode + '\nkeyText:' + event.keyText + '\nintentionCode:' + event.intentionCode
156          }
157        })
158      Text(this.text).padding(15)
159    }.height(300).width('100%').padding(35)
160  }
161}
162```
163
164 ![keyEvent](figures/keyEvent.gif)
165
166### 示例2（获取uniCode码值）
167
168该示例通过key事件获取到所按按键的unicode码值。
169
170```ts
171// xxx.ets
172@Entry
173@Component
174struct KeyEventExample {
175  @State text: string = ''
176  @State eventType: string = ''
177  @State keyType: string = ''
178
179  build() {
180    Column({ space: 10 }) {
181      Button('KeyEvent')
182        .onKeyEvent((event?: KeyEvent) => {
183          if(event){
184            if (event.type === KeyType.Down) {
185              this.eventType = 'Down'
186            }
187            if (event.type === KeyType.Up) {
188              this.eventType = 'Up'
189            }
190            if (event.unicode == 97) {
191              this.keyType = 'a'
192            } else if (event.unicode == 65) {
193              this.keyType = 'A'
194            } else {
195              this.keyType = ' '
196            }
197            this.text = 'KeyType:' + this.eventType + '\nUnicode:' + event.unicode + '\nkeyCode:' + event.keyCode + '\nkeyType:' + this.keyType
198          }
199        })
200      Text(this.text).padding(15)
201    }.height(300).width('100%').padding(35)
202  }
203}
204```
205
206![keyEvent](figures/keyEvent_unicode.gif)
207
208### 示例3（触发onKeyPreIme回调）
209
210该示例使用onKeyPreIme屏蔽在输入框中使用方向左键。
211
212```ts
213import { KeyCode } from '@kit.InputKit';
214
215@Entry
216@Component
217struct PreImeEventExample {
218  @State buttonText: string = '';
219  @State buttonType: string = '';
220  @State columnText: string = '';
221  @State columnType: string = '';
222
223  build() {
224    Column() {
225      Search({
226        placeholder: "Search..."
227      })
228        .width("80%")
229        .height("40vp")
230        .border({ radius:"20vp" })
231        .onKeyPreIme((event:KeyEvent) => {
232          // 使用方向左键不生效
233          if (event.keyCode == KeyCode.KEYCODE_DPAD_LEFT) {
234            return true;
235          }
236          return false;
237        })
238    }
239  }
240}
241```