1# Key Event
2
3A key event is triggered when a focusable component, such as **Button**, interacts with a keyboard, remote control, or any other input device with keys. To use a key event for components that are not focusable by default, such as **Text** and **Image**, first set their **focusable** attribute to **true**.
4For details about the process and specific timing of the key event triggering, see [Key Event Data Flow](../../../ui/arkts-common-events-device-input-event.md#key-event-data-flow).
5
6>  **NOTE**
7>
8>  The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
9
10## onKeyEvent
11
12onKeyEvent(event: (event: KeyEvent) => void): T
13
14Triggered when a key event occurs.
15
16**Atomic service API**: This API can be used in atomic services since API version 11.
17
18**System capability**: SystemCapability.ArkUI.ArkUI.Full
19
20**Parameters**
21
22| Name| Type                         | Mandatory| Description              |
23| ------ | ----------------------------- | ---- | ------------------ |
24| event  | [KeyEvent](#keyevent) | Yes  | **KeyEvent** object.|
25
26**Return value**
27
28| Type| Description|
29| -------- | -------- |
30| T | Current component.|
31
32## onKeyPreIme<sup>12+</sup>
33
34onKeyPreIme(event: Callback<KeyEvent, boolean>): T
35
36Triggered before other callbacks when a key event occurs.
37
38If the return value of this callback is **true**, it is considered that the key event has been consumed, and subsequent event callbacks (**keyboardShortcut**, input method events, **onKeyEvent**) will be intercepted and no longer triggered.
39
40**Atomic service API**: This API can be used in atomic services since API version 12.
41
42**System capability**: SystemCapability.ArkUI.ArkUI.Full
43
44**Parameters**
45
46| Name| Type                         | Mandatory| Description              |
47| ------ | ----------------------------- | ---- | ------------------ |
48| event  | [Callback](./ts-types.md#callback12)<[KeyEvent](#keyevent), boolean>| Yes  | Callback for processing the key event.|
49
50**Return value**
51
52| Type| Description|
53| -------- | -------- |
54| T | Current component.|
55
56## KeyEvent
57
58**Atomic service API**: This API can be used in atomic services since API version 11.
59
60**System capability**: SystemCapability.ArkUI.ArkUI.Full
61
62| Name                                   | Type                                      | Description                        |
63| ------------------------------------- | ---------------------------------------- | -------------------------- |
64| type                                  | [KeyType](ts-appendix-enums.md#keytype)  | Key type.                    |
65| [keyCode](../../apis-input-kit/js-apis-keycode.md#keycode) | number                                   | Key code.                    |
66| keyText                               | string                                   | Key value.                    |
67| keySource                             | [KeySource](ts-appendix-enums.md#keysource) | Type of the input device that triggers the key event.            |
68| deviceId                              | number                                   | ID of the input device that triggers the key event.            |
69| metaKey                               | number                                   | State of the meta key (that is, the **WIN** key on the Windows keyboard or the **Command** key on the Mac keyboard) when the key event occurs. The value **1** indicates that the key is pressed, and **0** indicates that the key is not pressed.|
70| timestamp                             | number                                   | Timestamp of the event. It is the interval between the time when the event is triggered and the time when the system starts, in nanoseconds.|
71| stopPropagation                       | () => void                               | Stops the event from bubbling upwards or downwards.                 |
72| intentionCode<sup>10+</sup>           | [IntentionCode](../../apis-input-kit/js-apis-intentioncode.md) | Intention corresponding to the key.      |
73| getModifierKeyState<sup>12+</sup> | (Array&lt;string&gt;) => bool | Obtains the pressed status of modifier keys. For details about the error message, see the following error codes. The following modifier keys are supported: 'Ctrl'\|'Alt'\|'Shift'\|'Fn'. However, the **Fn** key on external keyboards is not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 13.|
74| unicode<sup>14+</sup>                              | number                                   | Unicode value of the key. Non-space basic Latin characters in the 0x0021-0x007E range are supported. Characters with a value of 0 are not supported. In the case of key combination, this API returns the Unicode value of the key corresponding to the key event.<br>**Atomic service API**: This API can be used in atomic services since API version 14.|
75
76**Error codes**
77
78For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md).
79
80| ID| Error Message|
81| ------- | -------- |
82| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. |
83
84## Example 1
85
86```ts
87// xxx.ets
88@Entry
89@Component
90struct KeyEventExample {
91  @State text: string = ''
92  @State eventType: string = ''
93
94  build() {
95    Column() {
96      Button('KeyEvent')
97        .onKeyEvent((event?: KeyEvent) => {
98          if(event){
99            if (event.type === KeyType.Down) {
100              this.eventType = 'Down'
101            }
102            if (event.type === KeyType.Up) {
103              this.eventType = 'Up'
104            }
105            this.text = 'KeyType:' + this.eventType + '\nkeyCode:' + event.keyCode + '\nkeyText:' + event.keyText + '\nintentionCode:' + event.intentionCode
106          }
107        })
108      Text(this.text).padding(15)
109    }.height(300).width('100%').padding(35)
110  }
111}
112```
113
114 ![keyEvent](figures/keyEvent.gif)
115
116## Example 2
117This example shows how to obtain the Unicode value of the pressed key from a key event.
118
119```ts
120// xxx.ets
121@Entry
122@Component
123struct KeyEventExample {
124  @State text: string = ''
125  @State eventType: string = ''
126  @State keyType: string = ''
127
128  build() {
129    Column({ space: 10 }) {
130      Button('KeyEvent')
131        .onKeyEvent((event?: KeyEvent) => {
132          if(event){
133            if (event.type === KeyType.Down) {
134              this.eventType = 'Down'
135            }
136            if (event.type === KeyType.Up) {
137              this.eventType = 'Up'
138            }
139            if (event.unicode == 97) {
140              this.keyType = 'a'
141            } else if (event.unicode == 65) {
142              this.keyType = 'A'
143            } else {
144              this.keyType = ' '
145            }
146            this.text = 'KeyType:' + this.eventType + '\nUnicode:' + event.unicode + '\nkeyCode:' + event.keyCode + '\nkeyType:' + this.keyType
147          }
148        })
149      Text(this.text).padding(15)
150    }.height(300).width('100%').padding(35)
151  }
152}
153```
154
155![keyEvent](figures/keyEvent_unicode.gif)
156