1# 组件快捷键事件 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9开发者可以设置组件的自定义组合键，每个组件可以设置多个组合键。 10 11即使组件未获焦或是在所在页面未展示，只要已经挂载到获焦窗口的组件树上就会响应自定义组合键。 12 13开发者在设置组合键的同时可以设置自定义事件，组合键按下时，触发该自定义事件，若没有设置自定义事件，则组合键行为与click行为一致。 14 15> **说明：** 16> 17> 从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 18 19## keyboardShortcut 20 21keyboardShortcut(value: string | FunctionKey, keys: Array\<ModifierKey>, action?: () => void): T 22 23设置组件的自定义组合键。 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ----- | ------------------------------------- | ---- | ---------------------------------------- | 33| value | string \| [FunctionKey](ts-appendix-enums.md#functionkey10) | 是 | 热键的单个字符（可以通过键盘输入的字符）或[FunctionKey](ts-appendix-enums.md#functionkey10)。<br />空字符串意为取消快捷键绑定。<br/> | 34| keys | Array\<[ModifierKey](ts-appendix-enums.md#modifierkey10)> | 是 | 热键组合。<br />仅当value为[FunctionKey](ts-appendix-enums.md#functionkey10)的情况下可以为空。<br/> | 35| action | () => void | 否 | 组合快捷键触发成功后的自定义事件回调。<br/> | 36 37**返回值：** 38 39| 类型 | 说明 | 40| -------- | -------- | 41| T | 返回当前组件。 | 42 43## 快捷键使用注意事项 44 45快捷键是对系统按键的响应，优先于普通的按键事件`OnKeyEvent`，按键事件触发的逻辑详见[按键事件数据流](../../../ui/arkts-interaction-development-guide-keyboard.md#按键事件数据流)。 46 47| 场景 | 快捷键处理逻辑 | 例子 | 48| ---------------------------------------- | ---------------------------------- | ---------------------------------------- | 49| 所有支持onClick事件的组件 | 支持自定义组合键 | 无 | 50| 自定义组合键要求 | 控制键Ctrl、Shift、Alt及它们的组合加上其它可输入字符按键 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL]) | 51| 多个不同组件设置相同组合键 | 只响应结点树上的第一个组件，其它组件不响应快捷键。 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL])<br />Button('button2').keyboardShortcut('a',[ModifierKey.CTRL]) | 52| 无论组件是否获得焦点 | 只要窗口获焦，快捷键就会响应 | 无 | 53| 使用单个`FunctionKey`触发快捷键 | 单个`FunctionKey`，没有`ModifierKey`，可以绑定为快捷键 | Button('button1').keyboardShortcut(FunctionKey.F2,[]) | 54| `keyboardShortcut`的入参`value`为空 | 取消绑定的快捷键。<br />绑定多个快捷键的时候无法取消快捷键。| Button('button1').keyboardShortcut('',[ModifierKey.CTRL])<br />Button('button2').keyboardShortcut('',[]) | 55| 独立pipeline子窗口、主窗口共存的情况下 | 获焦的窗口响应快捷键 | 无 | 56| keyboardShortcut接口中的keys命令中ctrl、shift、alt | 不区分左右键都响应 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL, ModifierKey.ALT]) | 57| keyboardShortcut接口中的value单个字符 | 不区分大小写都响应 | Button('button1').keyboardShortcut('a',[ModifierKey.CTRL])<br />Button('button2').keyboardShortcut('A',[ModifierKey.CTRL]) | 58| 快捷键的响应 | `keys`键处于按下状态且`value`键触发down事件（长按会连续响应） | 无 | 59| 隐藏组件<br /> | 响应快捷键 | 无 | 60| disable状态组件 | 不响应快捷键 | 无 | 61| 1. 组件的组合键(包括系统预定义快捷键)相同时。<br />2. 接口参数value有多个字符时。<br />3. 接口参数keys有重复的控制键时。 | 这几种情况不绑定组合键，先前绑定的组合键仍然有效。 | Button('button1').keyboardShortcut(FunctionKey.F4,[ModifierKey.ALT])<br />Button('button2').keyboardShortcut('ab',[ModifierKey.CTRL])<br />Button('button3').keyboardShortcut('ab',[ModifierKey.CTRL,ModifierKey.CTRL]) | 62 63### 禁止绑定的系统快捷键 64 65以下组合键绑定为快捷键不生效。 66 67- `Alt` + `F4` 68- `Alt` + `Shift` + `F4` 69- `Alt` + `TAB` 70- `Alt` + `Shift` + `TAB` 71- `Ctrl` + `Shift` + `ESC` 72 73### 系统已存在的按键事件 74 75已存在如下系统响应的按键事件，具体规格如下表。 76 77表中的按键事件与自定义按键事件的触发有优先级关系，高优先级的事件会拦截低优先级事件，焦点事件响应优先级详见[按键事件数据流](../../../ui/arkts-interaction-development-guide-keyboard.md#按键事件数据流)。 78 79| 快捷键 | 获焦组件 | 用途 | 事件处理类别 | 80| ----- | ---- | ---- | ---- | 81| 方向键、Shift + 方向键 | 输入框组件 | 移动光标 | 输入法 | 82| 方向键、Shift + 方向键 | 通用组件 | 系统处于走焦状态时，用于方向走焦 | 系统按键 | 83| TAB、Shift + TAB | 通用组件 | 触发进入走焦状态/走焦 | 系统按键 | 84 85## 示例 86 87### 示例1（设置组件快捷键） 88 89该示例通过设置组件的快捷键，同时按控制键+对应的字符可以触发组件响应快捷键，并触发onClick事件或自定义事件。 90 91```ts 92@Entry 93@Component 94struct Index { 95 @State message: string = 'Hello World' 96 97 build() { 98 Row() { 99 Column({ space: 5 }) { 100 Text(this.message) 101 Button("Test short cut 1").onClick((event: ClickEvent) => { 102 this.message = "I clicked Button 1"; 103 console.info("I clicked 1"); 104 }).keyboardShortcut('.', [ModifierKey.SHIFT, ModifierKey.CTRL, ModifierKey.ALT]) 105 .onKeyEvent((event: KeyEvent)=>{ 106 console.info("event.keyCode: " + JSON.stringify(event)); 107 }) 108 Button("Test short cut 2").onClick((event: ClickEvent) => { 109 this.message = "I clicked Button 2"; 110 console.info("I clicked 2"); 111 }).keyboardShortcut('1', [ModifierKey.CTRL]) 112 Button("Test short cut 3").onClick((event: ClickEvent) => { 113 this.message = "I clicked Button 3"; 114 console.info("I clicked 3"); 115 }).keyboardShortcut('A', [ModifierKey.SHIFT]) 116 Button("Test short cut 4").onClick((event: ClickEvent) => { 117 this.message = "I clicked Button 4"; 118 console.info("I clicked 4"); 119 }).keyboardShortcut(FunctionKey.F5, [], () => { 120 this.message = "I clicked Button 4"; 121 console.info("I clicked user callback."); 122 }).keyboardShortcut(FunctionKey.F3, []) 123 } 124 .width('100%') 125 } 126 .height('100%') 127 } 128} 129``` 130 131  132 133### 示例2（注册和解注册快捷键绑定） 134 135该示例演示了如何实现按键注册和解注册快捷键绑定。 136 137```ts 138@Entry 139@Component 140struct Index { 141 @State message: string = 'disable' 142 @State shortCutEnable: boolean = false 143 @State keyValue: string = '' 144 145 build() { 146 Row() { 147 Column({ space: 5 }) { 148 Text('Ctrl+A is ' + this.message) 149 Button("Test short cut").onClick((event: ClickEvent) => { 150 this.message = "I clicked Button"; 151 console.info("I clicked"); 152 }).keyboardShortcut(this.keyValue, [ModifierKey.CTRL]) 153 Button(this.message + 'shortCut').onClick((event: ClickEvent) => { 154 this.shortCutEnable = !this.shortCutEnable; 155 this.message = this.shortCutEnable ? 'enable' : 'disable'; 156 this.keyValue = this.shortCutEnable ? 'a' : ''; 157 }) 158 Button('multi-shortcut').onClick((event: ClickEvent) => { 159 console.info('Trigger keyboard shortcut success.') 160 }).keyboardShortcut('q', [ModifierKey.CTRL]) 161 .keyboardShortcut('w', [ModifierKey.CTRL]) 162 .keyboardShortcut('', []) // 不生效，绑定了多个快捷键的组件不能取消快捷键 163 } 164 .width('100%') 165 } 166 .height('100%') 167 } 168} 169``` 170 171 
