Component Keyboard Shortcut Event

You 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.

NOTE

The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.

APIs

keyboardShortcut(value: string|[FunctionKey], keys: Array<[ModifierKey]>)

Parameters

Name	Type	Mandatory	Description
value	string \|FunctionKey	Yes	Character key (which can be entered through the keyboard) or function key.
keys	Array<ModifierKey>	Yes	Modifier keys.

ModifierKey

Name	Description
CTRL	Ctrl key on the keyboard.
SHIFT	Shift key on the keyboard.
ALT	Alt key on the keyboard.

FunctionKey

Name	Description
ESC	Esc key on the keyboard.
F1	F1 key on the keyboard.
F2	F2 key on the keyboard.
F3	F3 key on the keyboard.
F4	F4 key on the keyboard.
F5	F5 key on the keyboard.
F6	F6 key on the keyboard.
F7	F7 key on the keyboard.
F8	F8 key on the keyboard.
F9	F9 key on the keyboard.
F10	F10 key on the keyboard.
F11	F11 key on the keyboard.
F12	F12 key on the keyboard.

Precautions for Using Keyboard Shortcuts

Scenario	Processing Logic	Example
All components that support the onClick event	Custom keyboard shortcuts are supported.	–
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])
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]) Button('button2').keyboardShortcut('a',[ModifierKey.CTRL])
When the component is focused or not	The component responds to the custom keyboard shortcut as long as the window is focused.	–
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. When multiple keyboard shortcuts are set, they cannot be canceled.	Canceling the custom keyboard shortcut settings	Button('button1').keyboardShortcut('',[ModifierKey.CTRL]) Button('button2').keyboardShortcut('a',[l]) Button('button3').keyboardShortcut('',[])
The independent pipeline sub-window and main window coexist	The focused window responds to the keyboard shortcut.	–
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])
Character key in the value parameter of the keyboardShortcut API	The response is case-insensitive.	Button('button1').keyboardShortcut('a',[ModifierKey.CTRL]) Button('button2').keyboardShortcut('A',[ModifierKey.CTRL])
Response to keyboard shortcuts	The component responds continuously to the keyboard shortcut when all the set keys are pressed.	–
Hidden component	The keyboard shortcut also works.	–
Components in the disable state	The keyboard shortcut does not work.	–
1. The keyboard shortcut is the same as an existing one (including the system-defined ones). 2. The value parameter contains multiple character keys. 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]) Button('button2').keyboardShortcut('ab',[ModifierKey.CTRL]) Button('button3').keyboardShortcut('ab',[ModifierKey.CTRL,ModifierKey.CTRL])

System-defined Keyboard Shortcuts

Keyboard Shortcut	Component
Ctrl + C	Image, TextInput, TextArea
Ctrl+ A	TextInput, TextArea
Ctrl+ V	TextInput, TextArea
Ctrl+ X	TextInput, TextArea
Shift + arrow keys	TextInput, TextArea
Ctrl+ Shift+ Z	TextInput, TextArea
Ctrl+ Z	TextInput, TextArea
Ctrl+ Y	TextInput, TextArea
Arrow keys and Enter key	TextInput, TextArea
Tab key	TextInput, TextArea

Example

Set 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.

// xxx.ets
@Entry
@Component
struct Index {
  @State message: string = 'Hello World'

  build() {
    Row() {
      Column() {
        Text(this.message)
        Button("Test short cut 1").onClick((event) => {
          this.message = "I clicked Button 1";
          console.log("I clicked 1");
        }).keyboardShortcut('.', [ModifierKey.SHIFT, ModifierKey.CTRL, ModifierKey.ALT])
          .onKeyEvent((event)=>{
            console.log("event.keyCode: " + JSON.stringify(event));
          })
        Button("Test short cut 2").onClick((event) => {
          this.message = "I clicked Button 2";
          console.log("I clicked 2");
        }).keyboardShortcut('1', [ModifierKey.CTRL])
        Button("Test short cut 3").onClick((event) => {
          this.message = "I clicked Button 3";
          console.log("I clicked 3");
        }).keyboardShortcut('A', [ModifierKey.SHIFT])
        Button("Test short cut 4").onClick((event) => {
          this.message = "I clicked Button 4";
          console.log("I clicked 4");
        }).keyboardShortcut(FunctionKey.F5, [], () => {
          this.message = "I clicked Button 4";
          console.log("I clicked user callback.");
        }).keyboardShortcut(FunctionKey.F3, [])
      }
      .width('100%')
    }
    .height('100%')
  }
}