1# Component Keyboard Shortcut Event 2 3You can set one or more custom keyboard shortcuts for a component. The behavior of these keyboard shortcuts is the same as that of clicks. Components can respond to custom keyboard shortcuts even when they are not focused. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 8 9## APIs 10 11keyboardShortcut(value: string | FunctionKey, keys: Array<ModifierKey>, action?: () => void) 12 13**Parameters** 14 15| Name | Type | Mandatory | Description | 16| ----- | ------------------------------------- | ---- | ---------------------------------------- | 17| value | string \| [FunctionKey](#functionkey) | Yes | Character key (which can be entered through the keyboard) or [function key](#functionkey).<br>| 18| keys | Array<[ModifierKey](#modifierkey)> | Yes | Modifier keys.<br> | 19| action | () => void | No | Callback for a custom event after the keyboard shortcut is triggered.<br> | 20 21## ModifierKey 22 23| Name | Description | 24| ----- | ------------ | 25| CTRL | Ctrl key on the keyboard. | 26| SHIFT | Shift key on the keyboard.| 27| ALT | Alt key on the keyboard. | 28 29## FunctionKey 30 31| Name | Description | 32| ---- | ------------ | 33| ESC | Esc key on the keyboard.| 34| F1 | F1 key on the keyboard. | 35| F2 | F2 key on the keyboard. | 36| F3 | F3 key on the keyboard. | 37| F4 | F4 key on the keyboard. | 38| F5 | F5 key on the keyboard. | 39| F6 | F6 key on the keyboard. | 40| F7 | F7 key on the keyboard. | 41| F8 | F8 key on the keyboard. | 42| F9 | F9 key on the keyboard. | 43| F10 | F10 key on the keyboard.| 44| F11 | F11 key on the keyboard.| 45| F12 | F12 key on the keyboard.| 46 47## Precautions for Using Keyboard Shortcuts 48 49| Scenario | Processing Logic | Example | 50| ---------------------------------------- | ---------------------------------- | ---------------------------------------- | 51| All components that support the **onClick** event | Custom keyboard shortcuts are supported. | – | 52| Requirements for custom keyboard shortcuts | A custom keyboard shortcut consists of one or more modifier keys (**Ctrl**, **Shift**, **Alt**, or any combination thereof) and a character key or function key.| Button('button1').keyboardShortcut('a',[ModifierKey.CTRL]) | 53| Setting one custom keyboard shortcut for multiple components | Only the first component in the component tree responds to the custom keyboard shortcut. | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL])<br>Button('button2').keyboardShortcut('a',[ModifierKey.CTRL]) | 54| When the component is focused or not | The component responds to the custom keyboard shortcut as long as the window is focused. | – | 55| When a single keyboard shortcut is set, it can be canceled by setting the **value**, **keys**, or both of them to null in the **keyboardShortcut** API.<br>When multiple keyboard shortcuts are set, they cannot be canceled.| Canceling the custom keyboard shortcut settings | Button('button1').keyboardShortcut('',[ModifierKey.CTRL])<br>Button('button2').keyboardShortcut('a',[l])<br>Button('button3').keyboardShortcut('',[]) | 56| The independent pipeline sub-window and main window coexist | The focused window responds to the keyboard shortcut. | – | 57| Ctrl, Shift, or Alt key in the **keys** parameter of the **keyboardShortcut** API| Both the keys on the left or right sides of the keyboard work. | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL, ModifierKey.ALT]) | 58| Character key in the **value** parameter of the **keyboardShortcut** API | The response is case-insensitive. | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL])<br>Button('button2').keyboardShortcut('A',[ModifierKey.CTRL]) | 59| Response to keyboard shortcuts | The component responds continuously to the keyboard shortcut when all the set keys are pressed. | – | 60| Hidden component<br> | The keyboard shortcut also works. | – | 61| Components in the disable state | The keyboard shortcut does not work. | – | 62| 1. The keyboard shortcut is the same as an existing one (including the system-defined ones).<br>2. The **value** parameter contains multiple character keys.<br>3. The **key** parameter has a duplicate modifier key.| In these cases, the keyboard shortcut is not added, and the previously added keyboard shortcuts still work. | Button('button1').keyboardShortcut('c',[ModifierKey.CTRL])<br>Button('button2').keyboardShortcut('ab',[ModifierKey.CTRL])<br>Button('button3').keyboardShortcut('ab',[ModifierKey.CTRL,ModifierKey.CTRL]) | 63 64## System-defined Keyboard Shortcuts 65 66| Keyboard Shortcut | Component | 67| -------------- | ---------------------------------------- | 68| Ctrl + C | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 69| Ctrl+ A | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 70| Ctrl+ V | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 71| Ctrl+ X | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 72| Shift + arrow keys | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 73| Ctrl+ Shift+ Z | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 74| Ctrl+ Z | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 75| Ctrl+ Y | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 76| Arrow keys and Enter key | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 77| Tab key | [Image](ts-basic-components-image.md), [TextInput](ts-basic-components-textinput.md), [TextArea](ts-basic-components-textarea.md)| 78 79## Example 80 81Set a keyboard shortcut. You can then press the modifier key and accompanying key at the same time to trigger the component to respond to the shortcut and trigger the **onClick** event or other custom event. 82 83```ts 84// xxx.ets 85@Entry 86@Component 87struct Index { 88 @State message: string = 'Hello World' 89 90 build() { 91 Row() { 92 Column() { 93 Text(this.message) 94 Button("Test short cut 1").onClick((event) => { 95 this.message = "I clicked Button 1"; 96 console.log("I clicked 1"); 97 }).keyboardShortcut('.', [ModifierKey.SHIFT, ModifierKey.CTRL, ModifierKey.ALT]) 98 .onKeyEvent((event)=>{ 99 console.log("event.keyCode: " + JSON.stringify(event)); 100 }) 101 Button("Test short cut 2").onClick((event) => { 102 this.message = "I clicked Button 2"; 103 console.log("I clicked 2"); 104 }).keyboardShortcut('1', [ModifierKey.CTRL]) 105 Button("Test short cut 3").onClick((event) => { 106 this.message = "I clicked Button 3"; 107 console.log("I clicked 3"); 108 }).keyboardShortcut('A', [ModifierKey.SHIFT]) 109 Button("Test short cut 4").onClick((event) => { 110 this.message = "I clicked Button 4"; 111 console.log("I clicked 4"); 112 }).keyboardShortcut(FunctionKey.F5, [], () => { 113 this.message = "I clicked Button 4"; 114 console.log("I clicked user callback."); 115 }).keyboardShortcut(FunctionKey.F3, []) 116 } 117 .width('100%') 118 } 119 .height('100%') 120 } 121} 122``` 123