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 metakey (that is, the **WIN** key on the Windows keyboard or the **Command** key on the Mac keyboard) when the key is pressed. The value **1** indicates the pressed state, and **0** indicates the unpressed state. |
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'. This API does not work for the Fn key on an externally connected keyboard.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
74
75**Error codes**
76
77For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md).
78
79| ID | Error Message |
80| ------- | -------- |
81| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. |
82
83## Example
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 ![keyEvent](figures/keyEvent.gif) 
114