1# 组件快捷键事件 2 3开发者可以设置组件的自定义组合键，组合键的行为与click行为一致，组件在未获得焦点状态下也可以响应自定义组合键，每个组件可以设置多个组合键。 4 5> **说明：** 6> 7> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## keyboardShortcut 10 11keyboardShortcut(value: string | FunctionKey, keys: Array\<ModifierKey>, action?: () => void): T 12 13设置组件的自定义组合键。 14 15**系统能力：** SystemCapability.ArkUI.ArkUI.Full 16 17**参数：** 18 19| 参数名 | 参数类型 | 必填 | 参数描述 | 20| ----- | ------------------------------------- | ---- | ---------------------------------------- | 21| value | string \| [FunctionKey](#functionkey) | 是 | 热键的单个字符（可以通过键盘输入的字符）或[FunctionKey](#functionkey)。<br/> | 22| keys | Array\<[ModifierKey](#modifierkey)> | 是 | 热键组合。<br/> | 23| action | () => void | 否 | 组合快捷键触发成功后的自定义事件回调。<br/> | 24 25**返回值：** 26 27| 类型 | 说明 | 28| -------- | -------- | 29| T | 返回当前组件。 | 30 31## ModifierKey 32 33| 名称 | 描述 | 34| ----- | ------------ | 35| CTRL | 表示键盘上Ctrl键。 | 36| SHIFT | 表示键盘上Shift键。 | 37| ALT | 表示键盘上Alt键。 | 38 39## FunctionKey 40 41| 名称 | 描述 | 42| ---- | ------------ | 43| ESC | 表示键盘上ESC功能键。 | 44| F1 | 表示键盘上F1功能键。 | 45| F2 | 表示键盘上F2功能键。 | 46| F3 | 表示键盘上F3功能键。 | 47| F4 | 表示键盘上F4功能键。 | 48| F5 | 表示键盘上F5功能键。 | 49| F6 | 表示键盘上F6功能键。 | 50| F7 | 表示键盘上F7功能键。 | 51| F8 | 表示键盘上F8功能键。 | 52| F9 | 表示键盘上F9功能键。 | 53| F10 | 表示键盘上F10功能键。 | 54| F11 | 表示键盘上F11功能键。 | 55| F12 | 表示键盘上F12功能键。 | 56 57## 快捷键使用注意事项 58 59| 场景 | 快捷键处理逻辑 | 例子 | 60| ---------------------------------------- | ---------------------------------- | ---------------------------------------- | 61| 所有支持onClick事件的组件 | 支持自定义组合键 | 无 | 62| 自定义组合键要求 | 控制键Ctrl、Shift、Alt及它们的组合加上其它可输入字符按键 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL]) | 63| 多个不同组件设置相同组合键 | 只响应结点树上的第一个组件，其它组件不响应快捷键。 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL])<br />Button('button2').keyboardShortcut('a',[ModifierKey.CTRL]) | 64| 无论组件是否获得焦点 | 只要窗口获焦快捷键就会响应 | 无 | 65| 绑定单个快捷键时候，通过keyboardShortcut接口value值或者是keys值或两者都是空的情况下。<br />绑定多个快捷键的时候无法取消快捷键。 | 取消快捷键的设置 | Button('button1').keyboardShortcut('',[ModifierKey.CTRL])<br />Button('button2').keyboardShortcut('a',[l])<br />Button('button3').keyboardShortcut('',[]) | 66| 独立pipeline子窗口、主窗口共存的情况下 | 获焦的窗口响应快捷键 | 无 | 67| keyboardShortcut接口中的keys命令中ctrl、shift、alt | 不区分左右键都响应 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL, ModifierKey.ALT]) | 68| keyboardShortcut接口中的value单个字符 | 不区分大小写都响应 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL])<br />Button('button2').keyboardShortcut('A',[ModifierKey.CTRL]) | 69| 快捷键的响应 | 所有快捷键down的状态下响应、且连续响应 | 无 | 70| 隐藏组件<br /> | 响应快捷键 | 无 | 71| disable状态组件 | 不响应快捷键 | 无 | 72| 1. 组件的组合键(包括系统预定义快捷键)相同时。<br />2. 接口参数value有多个字符时。<br />3. 接口参数keys有重复的控制键时。 | 这几种情况不绑定组合键, 先前绑定的组合键仍然有效 | Button('button1').keyboardShortcut('c',[ModifierKey.CTRL])<br />Button('button2').keyboardShortcut('ab',[ModifierKey.CTRL])<br />Button('button3').keyboardShortcut('ab',[ModifierKey.CTRL,ModifierKey.CTRL]) | 73 74## 系统已有组合键 75 76| 快捷键 | 组件 | 77| -------------- | ---------------------------------------- | 78| Ctrl + C | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 79| Ctrl+ A | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 80| Ctrl+ V | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 81| Ctrl+ X | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 82| Shift + 方向键 | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 83| Ctrl+ Shift+ Z | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 84| Ctrl+ Z | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 85| Ctrl+ Y | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 86| 方向键、回车键 | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 87| TAB键 | [Image](ts-basic-components-image.md)、[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md) | 88 89## 示例 90 91设置组件的快捷键，同时按控制键+对应的字符可以触发组件响应快捷键，并触发onClick事件或自定义事件。 92 93```ts 94// xxx.ets 95@Entry 96@Component 97struct Index { 98 @State message: string = 'Hello World' 99 100 build() { 101 Row() { 102 Column() { 103 Text(this.message) 104 Button("Test short cut 1").onClick((event) => { 105 this.message = "I clicked Button 1"; 106 console.log("I clicked 1"); 107 }).keyboardShortcut('.', [ModifierKey.SHIFT, ModifierKey.CTRL, ModifierKey.ALT]) 108 .onKeyEvent((event)=>{ 109 console.log("event.keyCode: " + JSON.stringify(event)); 110 }) 111 Button("Test short cut 2").onClick((event) => { 112 this.message = "I clicked Button 2"; 113 console.log("I clicked 2"); 114 }).keyboardShortcut('1', [ModifierKey.CTRL]) 115 Button("Test short cut 3").onClick((event) => { 116 this.message = "I clicked Button 3"; 117 console.log("I clicked 3"); 118 }).keyboardShortcut('A', [ModifierKey.SHIFT]) 119 Button("Test short cut 4").onClick((event) => { 120 this.message = "I clicked Button 4"; 121 console.log("I clicked 4"); 122 }).keyboardShortcut(FunctionKey.F5, [], () => { 123 this.message = "I clicked Button 4"; 124 console.log("I clicked user callback."); 125 }).keyboardShortcut(FunctionKey.F3, []) 126 } 127 .width('100%') 128 } 129 .height('100%') 130 } 131} 132``` 133