1# Component Keyboard Shortcut Event 2 3You can set custom keyboard shortcuts for components, with the flexibility to define multiple shortcuts per component. 4 5A component will still respond to the set custom shortcuts even if it's not in focus or visible on the active page, as long as it's part of the component tree within a window that has focus. 6 7Better yet, you can set custom events for custom keyboard shortcuts, so that when the defined keys of a keyboard shortcut are pressed, the custom event is triggered. If no custom event is set, the behavior of a keyboard shortcut is the same as that of a click. 8 9> **NOTE** 10> 11> The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 12 13## keyboardShortcut 14 15keyboardShortcut(value: string | FunctionKey, keys: Array\<ModifierKey>, action?: () => void): T 16 17Sets a keyboard shortcut for the component. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name | Type | Mandatory | Description | 26| ----- | ------------------------------------- | ---- | ---------------------------------------- | 27| value | string \| [FunctionKey](ts-appendix-enums.md#functionkey10) | Yes| Character key (which can be entered through the keyboard) or [function key](ts-appendix-enums.md#functionkey10).<br>An empty string means to disable the keyboard shortcut.<br>| 28| keys | Array\<[ModifierKey](ts-appendix-enums.md#modifierkey10)> | Yes| Modifier keys.<br>This parameter can be left empty only when **value** is set to a [function key](ts-appendix-enums.md#functionkey10).<br>| 29| action | () => void | No | Callback for a custom event after the keyboard shortcut is triggered.<br> | 30 31**Return value** 32 33| Type| Description| 34| -------- | -------- | 35| T | Current component.| 36 37## Precautions for Using Keyboard Shortcuts 38 39Keyboard shortcuts, as system keys, take precedence over the common key event **OnKeyEvent**. For details about the key event triggering logic, see [Key Event Data Flow](../../../ui/arkts-common-events-device-input-event.md#key-event-data-flow). 40 41| Scenario | Processing Logic | Example | 42| ---------------------------------------- | ---------------------------------- | ---------------------------------------- | 43| All components that support the **onClick** event | Custom keyboard shortcuts are supported. | – | 44| 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]) | 45| 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]) | 46| When the component is focused or not | The component responds to the custom keyboard shortcut as long as the window is focused. | – | 47| Using a single function key to trigger a keyboard shortcut| A keyboard shortcut can consist of a single function key without any modifier keys.| Button('button1').keyboardShortcut(FunctionKey.F2,[]) | 48| The input parameter **value** of **keyboardShortcut** is empty| The keyboard shortcut is disabled.<br>This does not apply when there are multiple keyboard shortcuts.| Button('button1').keyboardShortcut('',[ModifierKey.CTRL])<br>Button('button2').keyboardShortcut('',[]) | 49| The independent pipeline subwindow and main window coexist | The focused window responds to the keyboard shortcut. | – | 50| The input parameter **keys** of **keyboardShortcut** is set to the Ctrl, Shift, or Alt key| Both the keys on the left or right sides of the keyboard work. | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL, ModifierKey.ALT]) | 51| 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]) | 52| Response to keyboard shortcuts | The component responds to a keyboard shortcut when the keys specified by **keys** are pressed and the key specified by **value** triggers a down event. (Long-pressing leads to continuous response.) | – | 53| The component is hidden<br> | The component still responds to keyboard shortcuts. | – | 54| The component is in the disabled state | The component does not respond to keyboard shortcuts. | – | 55| 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(FunctionKey.F4,[ModifierKey.ALT])<br>Button('button2').keyboardShortcut('ab',[ModifierKey.CTRL])<br>Button('button3').keyboardShortcut('ab',[ModifierKey.CTRL,ModifierKey.CTRL]) | 56 57### System-defined Keyboard Shortcuts That Cannot Be Bound 58 59The following key combinations cannot function as keyboard shortcuts: 60 61- `Alt` + `F4` 62- `Alt` + `Shift` + `F4` 63- `Alt` + `TAB` 64- `Alt` + `Shift` + `TAB` 65- `Ctrl` + `Shift` + `ESC` 66 67### Predefined Key Events 68 69The following table lists the predefined key events. 70 71The predefined key events and custom key events have priorities. Events with higher priorities intercept those with lower priorities. For details about the response priorities, see [Key Event Data Flow](../../../ui/arkts-common-events-device-input-event.md#key-event-data-flow). 72 73| Keyboard Shortcut| Focused Component| Usage| Event Handling Category| 74| ----- | ---- | ---- | ---- | 75| Arrow keys, **Shift** + Arrow keys| Text box component| Moves the cursor.| Input method| 76| Arrow keys, **Shift** + Arrow keys| Universal component| Moves focus in navigation.| System keys| 77| **Tab**, **Shift** + **Tab**| Universal component| Triggers focus navigation or moves focus in navigation.| System keys| 78 79## Example 80 81### Example 1: Setting Component Keyboard Shortcuts 82 83This example demonstrates how to set up keyboard shortcuts for components. This allows users to 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 a custom event. 84 85```ts 86@Entry 87@Component 88struct Index { 89 @State message: string = 'Hello World' 90 91 build() { 92 Row() { 93 Column({ space: 5 }) { 94 Text(this.message) 95 Button("Test short cut 1").onClick((event: ClickEvent) => { 96 this.message = "I clicked Button 1"; 97 console.log("I clicked 1"); 98 }).keyboardShortcut('.', [ModifierKey.SHIFT, ModifierKey.CTRL, ModifierKey.ALT]) 99 .onKeyEvent((event: KeyEvent)=>{ 100 console.log("event.keyCode: " + JSON.stringify(event)); 101 }) 102 Button("Test short cut 2").onClick((event: ClickEvent) => { 103 this.message = "I clicked Button 2"; 104 console.log("I clicked 2"); 105 }).keyboardShortcut('1', [ModifierKey.CTRL]) 106 Button("Test short cut 3").onClick((event: ClickEvent) => { 107 this.message = "I clicked Button 3"; 108 console.log("I clicked 3"); 109 }).keyboardShortcut('A', [ModifierKey.SHIFT]) 110 Button("Test short cut 4").onClick((event: ClickEvent) => { 111 this.message = "I clicked Button 4"; 112 console.log("I clicked 4"); 113 }).keyboardShortcut(FunctionKey.F5, [], () => { 114 this.message = "I clicked Button 4"; 115 console.log("I clicked user callback."); 116 }).keyboardShortcut(FunctionKey.F3, []) 117 } 118 .width('100%') 119 } 120 .height('100%') 121 } 122} 123``` 124 125  126 127### Example 2: Registering and Unregistering Keyboard Shortcuts 128 129This example demonstrates how to register and unregister keyboard shortcuts dynamically. 130 131```ts 132@Entry 133@Component 134struct Index { 135 @State message: string = 'disable' 136 @State shortCutEnable: boolean = false 137 @State keyValue: string = '' 138 139 build() { 140 Row() { 141 Column({ space: 5 }) { 142 Text('Ctrl+A is ' + this.message) 143 Button("Test short cut").onClick((event: ClickEvent) => { 144 this.message = "I clicked Button"; 145 console.log("I clicked"); 146 }).keyboardShortcut(this.keyValue, [ModifierKey.CTRL]) 147 Button(this.message + 'shortCut').onClick((event: ClickEvent) => { 148 this.shortCutEnable = !this.shortCutEnable; 149 this.message = this.shortCutEnable ? 'enable' : 'disable'; 150 this.keyValue = this.shortCutEnable ? 'a' : ''; 151 }) 152 Button('multi-shortcut').onClick((event: ClickEvent) => { 153 console.log('Trigger keyboard shortcut success.') 154 }).keyboardShortcut('q', [ModifierKey.CTRL]) 155 .keyboardShortcut('w', [ModifierKey.CTRL]) 156 .keyboardShortcut('', []) // Disabling does not work when there are multiple keyboard shortcuts. 157 } 158 .width('100%') 159 } 160 .height('100%') 161 } 162} 163``` 164 165  166
