1# 焦点控制 2 3自定义组件的走焦效果，可设置组件是否走焦和具体的走焦顺序，tab键或者方向键切换焦点。 4 5> **说明：** 6> 7> - 从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - 自定义组件无获焦能力，当设置[focusable](#focusable)、[enabled](ts-universal-attributes-enable.md#enabled)等属性为false，或者设置[visibility](ts-universal-attributes-visibility.md#visibility)属性为Hidden、None时，也不影响其子组件的获焦。 10> 11> - 组件主动获取焦点不受窗口焦点的控制。 12> 13> - 焦点开发参考[焦点开发指南](../../../ui/arkts-common-events-focus-event.md)。 14 15## focusable 16 17focusable(value: boolean) 18 19设置当前组件是否可以获焦。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------ | ------- | ---- | ------------------------------------------------------------ | 29| value | boolean | 是 | 设置当前组件是否可以获焦，true表示组件可以获焦，false表示组件不可获焦。<br/>**说明：**<br/>存在默认交互逻辑的组件例如[Button](ts-basic-components-button.md)、[TextInput](ts-basic-components-textinput.md)等，默认即为可获焦，[Text](ts-basic-components-text.md)、[Image](ts-basic-components-image.md)等组件则默认状态为不可获焦。不可获焦状态下，无法触发[焦点事件](ts-universal-focus-event.md)。 | 30 31## tabIndex<sup>9+</sup> 32 33tabIndex(index: number) 34 35自定义组件tab键走焦能力。 36 37**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 38 39**系统能力：** SystemCapability.ArkUI.ArkUI.Full 40 41**参数：** 42 43| 参数名 | 类型 | 必填 | 说明 | 44| ------ | ------ | ---- | ------------------------------------------------------------ | 45| index | number | 是 | 自定义组件tab键走焦能力。若有配置了tabIndex大于0的组件，则tab键走焦只会在tabIndex大于0的组件内按照tabIndex的值从小到大并循环依次走焦。若没有配置tabIndex大于0的组件，则tabIndex等于0的组件按照组件预设的走焦规则走焦。<br />[UiExtension](../js-apis-arkui-uiExtension.md)组件未适配tabIndex，在含有[UiExtension](../js-apis-arkui-uiExtension.md)组件的页面使用tabIndex会导致走焦错乱。<br />- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素。<br />- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素。<br/>默认值：0 <br/> **说明：**<br/> tabIndex与focusScopeId不能混用。 46| 47 48## defaultFocus<sup>9+</sup> 49 50defaultFocus(value: boolean) 51 52设置当前组件是否为当前页面上的默认焦点。 53 54**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 55 56**系统能力：** SystemCapability.ArkUI.ArkUI.Full 57 58**参数：** 59 60| 参数名 | 类型 | 必填 | 说明 | 61| ------ | ------- | ---- | ------------------------------------------------------------ | 62| value | boolean | 是 | 设置当前组件是否为当前页面上的默认焦点，仅在初次创建的页面第一次进入时生效。<br/>默认值：false<br/>**说明：** <br/>值为true则表示为默认焦点，值为false无效。<br/>若页面内无任何组件设置defaultFocus(true)，API version 11及之前，页面的默认焦点是当前页面上首个可获焦的非容器组件，API version 11之后，页面的默认焦点就是页面的根容器。<br/>若某页面内有多个组件设置了defaultFocus(true)，则以组件树深度遍历找到的第一个组件为默认焦点。 | 63 64## groupDefaultFocus<sup>9+</sup> 65 66groupDefaultFocus(value: boolean) 67 68设置当前组件是否为当前组件所在容器获焦时的默认焦点。 69 70**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 71 72**系统能力：** SystemCapability.ArkUI.ArkUI.Full 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| ------ | ------- | ---- | ------------------------------------------------------------ | 78| value | boolean | 是 | 设置当前组件是否为当前组件所在容器获焦时的默认焦点，仅在初次创建容器节点第一次获焦时生效。true表示当前组件为所在容器获焦时的默认焦点，false表示当前组件不是所在容器获焦时的默认焦点。<br/>默认值：false<br/>**说明：** <br/>必须与[tabIndex](#tabindex9)联合使用，当某个容器设置了tabIndex，且容器内某子组件或容器自身设置了groupDefaultFocus(true)，当该容器首次TAB键获焦时，会自动将焦点转移至该指定的组件上。若容器内（包含容器本身）有多个组件设置了groupDefaultFocus(true)，则以组件树深度遍历找到的第一个组件为最终结果。 | 79 80## focusOnTouch<sup>9+</sup> 81 82focusOnTouch(value: boolean) 83 84设置当前组件是否支持点击获焦能力。 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ------ | ------- | ---- | ------------------------------------------------------------ | 94| value | boolean | 是 | 设置当前组件是否支持点击获焦能力。true表示组件支持点击获焦，false表示不支持点击获焦。<br/>默认值：false<br/>**说明：** <br/>仅在组件可点击时才能正常获取焦点。 | 95 96## focusBox<sup>12+</sup> 97 98focusBox(style: FocusBoxStyle): T 99 100设置当前组件系统焦点框样式。 101 102**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| ---- | ---- | ---- | ---- | 110| style | [FocusBoxStyle](#focusboxstyle12对象说明) | 是 | 设置当前组件系统焦点框样式。<br/>**说明：** <br/>该样式仅影响走焦状态下展示了系统焦点框的组件。 | 111 112 113## focusControl<sup>9+</sup> 114 115焦点控制模块 116 117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 118 119### requestFocus<sup>9+</sup> 120 121requestFocus(value: string): boolean 122 123方法语句中可使用的全局接口，调用此接口可以主动让焦点转移至参数指定的组件上。非当前帧生效，在下一帧才生效，建议使用FocusController中的[requestFocus](../js-apis-arkui-UIContext.md#requestfocus12)。 124 125**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 126 127**参数：** 128 129| 名称 | 类型 | 必填 | 描述 | 130| ----- | ------ | ---- | ---- | 131| value | string | 是 | 目标组件使用接口key(value: string)或id(value: string)绑定的字符串。 | 132 133**返回值：** 134 135| 类型 | 说明 | 136| ------- | ---- | 137| boolean | 返回是否成功给目标组件申请到焦点。若参数指向的目标组件存在，且目标组件可获焦，则返回true，否则返回false。 | 138 139> **说明：** 140> 141> 支持焦点控制的组件：[TextInput](ts-basic-components-textinput.md)、[TextArea](ts-basic-components-textarea.md)、[Search](ts-basic-components-search.md)、[Button](ts-basic-components-button.md)、[Text](ts-basic-components-text.md)、[Image](ts-basic-components-image.md)、[List](ts-container-list.md)、[Grid](ts-container-grid.md)。焦点事件当前仅支持在真机上显示运行效果。 142 143## FocusBoxStyle<sup>12+</sup>对象说明 144 145**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 146 147| 名称 | 参数类型 | 必填 | 描述 | 148| ---- | ---- | ---- | ---- | 149| margin | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 焦点框相对组件边缘的距离。<br/>正数代表外侧，负数代表内侧。不支持百分比。 | 150| strokeColor | [ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12) | 否 | 焦点框颜色。 | 151| strokeWidth | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 焦点框宽度。<br/>不支持负数与百分比。| 152 153## focusScopePriority<sup>12+</sup> 154 155focusScopePriority(scopeId: string, priority?: FocusPriority): T 156 157设置当前组件在指定容器内获焦的优先级。需要配合focusScopeId一起使用。 158 159**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 160 161**系统能力：** SystemCapability.ArkUI.ArkUI.Full 162 163**参数：** 164 165| 参数名 | 类型 | 必填 | 说明 | 166| ------ | ------- | ---- | ------------------------------------------------------------ | 167| scopeId | string | 是 | 当前组件设置的获焦优先级生效的容器组件的id标识。<br/>**说明：** <br/>1.当前组件必须在scopeId所标识的容器内或者当前组件所属容器在scopeId所标识的容器内。<br/>2.组件不可重复设置多个优先级。<br/>3.设置了focusScopeId的容器组件不可设置优先级。 | 168| priority | [FocusPriority](#focuspriority12) | 否 | 获焦优先级。<br/>**说明：** <br/>priority不设置则组件为默认AUTO优先级。<br/>优先级对走焦以及获焦组件的影响：<br/>1.容器整体获焦（层级页面切换/焦点切换到焦点组/容器组件使用requestFocus申请焦点）时，若容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由容器内上次获焦的组件获焦；<br/>2.容器非整体获焦（非焦点组场景下使用tab键/方向键走焦）时，若容器为首次获焦，则容器内优先级最高的组件获焦，若容器非首次获焦，不考虑优先级按照位置顺序走焦。 | 169 170### FocusPriority<sup>12+</sup> 171 172**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176| 名称 | 描述 | 177| ----------- | --------- | 178| AUTO | 默认的优先级，缺省时组件的获焦优先级。 | 179| PRIOR | 容器内优先获焦的优先级。优先级高于AUTO。 | 180| PREVIOUS | 上一次容器整体失焦时获焦节点的优先级。优先级高于PRIOR。 | 181 182### KeyProcessingMode<sup>15+</sup> 183 184设置按键事件处理的优先级。 185 186**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 187 188**系统能力：** SystemCapability.ArkUI.ArkUI.Full 189 190| 名称 | 值 | 说明 | 191| -----------| ----------- | --------- | 192| FOCUS_NAVIGATION | 0 | 默认值，当前组件不消费按键时，tab/方向键优先在当前容器内走焦。 | 193| ANCESTOR_EVENT | 1 | 当前组件不消费按键时，tab/方向键优先冒泡给父组件。 | 194 195## focusScopeId<sup>12+</sup> 196 197focusScopeId(id: string, isGroup?: boolean) 198 199设置当前容器组件的id标识，设置当前容器组件是否为焦点组。 200 201**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 202 203**系统能力：** SystemCapability.ArkUI.ArkUI.Full 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ------ | ------- | ---- | ------------------------------------------------------------ | 209| id | string | 是 | 设置当前容器组件的id标识。<br/>**说明：** <br/>单个层级页面下，id标识全局唯一，不可重复。 | 210| isGroup | boolean | 否 | 设置当前容器组件是否为焦点组。true表示容器组件为焦点组，false表示容器组件不是焦点组。<br/>**说明：** <br/>焦点组不可嵌套，不可重复配置。<br/> 焦点组不能和tabIndex混用。<br/>配置焦点组的目的时使得容器及容器内的元素可以按照焦点组规则走焦。焦点组走焦规则：<br/>1.焦点组容器内只能通过方向键走焦，tab键会使焦点跳出焦点组容器。<br/>2.通过方向键使焦点从焦点组容器外切换到焦点组容器内时，若焦点组容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由焦点组容器内上次获焦的组件获焦。| 211 212## focusScopeId<sup>14+</sup> 213 214focusScopeId(id: string, isGroup?: boolean, arrowStepOut?: boolean) 215 216设置当前容器组件的id标识，设置当前容器组件是否为焦点组。 217 218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 219 220**参数：** 221 222| 参数名 | 类型 | 必填 | 说明 | 223| ------ | ------- | ---- | ------------------------------------------------------------ | 224| id | string | 是 | 设置当前容器组件的id标识。<br/>**说明：** <br/>单个层级页面下，id标识全局唯一，不可重复。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 225| isGroup | boolean | 否 | 设置当前容器组件是否为焦点组。true表示容器组件为焦点组，false表示容器组件不是焦点组。<br/>**说明：** <br/>焦点组不可嵌套，不可重复配置。<br/> 焦点组不能和tabIndex混用。<br/>配置焦点组的目的时使得容器及容器内的元素可以按照焦点组规则走焦。焦点组走焦规则：<br/>1.焦点组容器内只能通过方向键走焦，tab键会使焦点跳出焦点组容器。<br/>2.通过方向键使焦点从焦点组容器外切换到焦点组容器内时，若焦点组容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由焦点组容器内上次获焦的组件获焦。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 226| arrowStepOut<sup>14+</sup> | boolean | 否 | 设置能否使用方向键走焦出当前焦点组。true表示可以使用方向键走焦出当前焦点组，false表示不能使用方向键走焦出当前焦点组。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 227 228## tabStop<sup>14+</sup> 229 230tabStop(isTabStop: boolean) :T 231 232设置当前容器组件的tabStop，可决定在走焦时焦点是否会停留在当前容器。 233 234**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| ------ | ------- | ---- | ------------------------------------------------------------ | 242| isTabStop | boolean | 是 | 设置当前容器组件是否为走焦可停留容器。true表示当前容器组件为走焦可停留容器，false表示当前容器组件不是走焦可停留容器。<br/>**说明：** <br/>1.配置tabStop需要保障是容器组件且有可获焦的孩子组件，默认容器组件不能直接获焦。<br/> 2.通过[requestFocus](../js-apis-arkui-UIContext.md#requestfocus12)请求焦点，如果是容器组件且配置tabStop，焦点能够停留在容器组件，如果未配置tabStop，即使整条焦点链上有配置了tabStop的组件，该组件依然能获取到焦点。<br/>3.配置tabStop的容器不允许嵌套超过2层。<br/>tabStop走焦规则：<br/>1.通过tab键和方向键走焦，焦点会停留在配置了tabStop的组件上，如果焦点停留在配置了tabStop的容器内部时，可以走焦到容器内部的下一个可获焦组件，如果焦点停留在配置了tabStop的容器外部时，可以走焦到容器外的下一个可获焦组件。<br/>2.当焦点停留在tabStop上时，按Enter键可以走焦到内部第一个可获焦组件，按ESC能够将焦点退回到不超过当前层级页面根容器的上一个配置了tabStop的组件，按空格键可以响应该容器的onClick事件。<br/>3.不建议根容器配置tabStop。如果根容器配置了tabStop，通过[clearFocus](../js-apis-arkui-UIContext.md#clearfocus12)将焦点清理到根容器，再按Enter键会重新走回内部上一次获焦组件，通过ESC键将焦点清理到根容器，再按Enter键会走焦到内部第一个可获焦组件。| 243 244**描述走焦的时候的按键以及获焦组件** 245 246 247 248当前焦点如果停留在button2时，按下tab键将会走焦到Column3上，再按下tab键会循环走焦到button1上。 249 250## nextFocus<sup>18+</sup> 251 252nextFocus(nextStep: Optional\<FocusMovement>): T 253 254设置组件的自定义焦点走焦的逻辑。 255 256**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 257 258**系统能力：** SystemCapability.ArkUI.ArkUI.Full 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| ------ | ------- | ---- | ------------------------------------------------------------ | 264| nextStep | [FocusMovement](#focusmovement18对象说明) | 否 | 设置当前容器组件的自定义走焦规则。<br/>**说明：** <br/>默认值为重置nextStep为空。<br/>没设置自定义走焦或者设置自定义组件容器不存在，仍进行默认走焦规则。| 265 266## FocusMovement<sup>18+</sup>对象说明 267 268设置对应的按键对应的走焦目的组件，缺省则遵循默认走焦规则。 269 270**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 271 272**系统能力：** SystemCapability.ArkUI.ArkUI.Full 273 274| 名称 | 类型 | 只读/可选 | 说明 | 275| ---- | ---- | ---- | ---- | 276| forward | string | 可选 | 通过tab键走焦到组件的id。<br/>默认值为重置forward为空。 | 277| backward | string | 可选 | 通过shift+tab键走焦到组件的id。<br/>默认值为重置backward为空。 | 278| up | string | 可选 | 通过方向键上键走焦到组件的id。<br/>默认值为重置up为空。 | 279| down | string | 可选 | 通过方向键下键走焦到组件的id。<br/>默认值为重置down为空。 | 280| left | string | 可选 | 通过方向键左键走焦到组件的id。<br/>默认值为重置left为空。 | 281| right | string | 可选 | 通过方向键右键走焦到组件的id。<br/>默认值为重置right为空。 | 282 283## 示例 284 285### 示例1（设置组件获焦和走焦的效果） 286 287该示例通过配置defaultFocus可以使绑定的组件成为页面创建后首次获焦的焦点，配置groupDefaultFocus可以使绑定的组件成为tabIndex容器创建后首次获焦的焦点，配置focusOnTouch可以使绑定的组件点击后立即获焦。 288 289```ts 290// focusTest.ets 291@Entry 292@Component 293struct FocusableExample { 294 @State inputValue: string = '' 295 296 build() { 297 Scroll() { 298 Row({ space: 20 }) { 299 Column({ space: 20 }) { 300 Column({ space: 5 }) { 301 Button('Group1') 302 .width(165) 303 .height(40) 304 .fontColor(Color.White) 305 .focusOnTouch(true) // 该Button组件点击后可获焦 306 Row({ space: 5 }) { 307 Button() 308 .width(80) 309 .height(40) 310 .fontColor(Color.White) 311 Button() 312 .width(80) 313 .height(40) 314 .fontColor(Color.White) 315 .focusOnTouch(true) // 该Button组件点击后可获焦 316 } 317 Row({ space: 5 }) { 318 Button() 319 .width(80) 320 .height(40) 321 .fontColor(Color.White) 322 Button() 323 .width(80) 324 .height(40) 325 .fontColor(Color.White) 326 } 327 }.borderWidth(2).borderColor(Color.Red).borderStyle(BorderStyle.Dashed) 328 .tabIndex(1) // 该Column组件为按TAB键走焦的第一个获焦的组件 329 Column({ space: 5 }) { 330 Button('Group2') 331 .width(165) 332 .height(40) 333 .fontColor(Color.White) 334 Row({ space: 5 }) { 335 Button() 336 .width(80) 337 .height(40) 338 .fontColor(Color.White) 339 Button() 340 .width(80) 341 .height(40) 342 .fontColor(Color.White) 343 .groupDefaultFocus(true) // 该Button组件上级Column组件获焦时获焦 344 } 345 Row({ space: 5 }) { 346 Button() 347 .width(80) 348 .height(40) 349 .fontColor(Color.White) 350 Button() 351 .width(80) 352 .height(40) 353 .fontColor(Color.White) 354 } 355 }.borderWidth(2).borderColor(Color.Green).borderStyle(BorderStyle.Dashed) 356 .tabIndex(2) // 该Column组件为按TAB键走焦的第二个获焦的组件 357 } 358 Column({ space: 5 }) { 359 TextInput({placeholder: 'input', text: this.inputValue}) 360 .onChange((value: string) => { 361 this.inputValue = value 362 }) 363 .width(156) 364 .defaultFocus(true) // 该TextInput组件为页面的初始默认焦点 365 Button('Group3') 366 .width(165) 367 .height(40) 368 .fontColor(Color.White) 369 Row({ space: 5 }) { 370 Button() 371 .width(80) 372 .height(40) 373 .fontColor(Color.White) 374 Button() 375 .width(80) 376 .height(40) 377 .fontColor(Color.White) 378 } 379 Button() 380 .width(165) 381 .height(40) 382 .fontColor(Color.White) 383 Row({ space: 5 }) { 384 Button() 385 .width(80) 386 .height(40) 387 .fontColor(Color.White) 388 Button() 389 .width(80) 390 .height(40) 391 .fontColor(Color.White) 392 } 393 Button() 394 .width(165) 395 .height(40) 396 .fontColor(Color.White) 397 Row({ space: 5 }) { 398 Button() 399 .width(80) 400 .height(40) 401 .fontColor(Color.White) 402 Button() 403 .width(80) 404 .height(40) 405 .fontColor(Color.White) 406 } 407 }.borderWidth(2).borderColor(Color.Orange).borderStyle(BorderStyle.Dashed) 408 .tabIndex(3) // 该Column组件为按TAB键走焦的第三个获焦的组件 409 }.alignItems(VerticalAlign.Top) 410 } 411 } 412} 413``` 414示意图： 415 416首次进入，焦点默认在defaultFocus绑定的TextInput组件上： 417 418 419 420首次按TAB键，焦点切换到tabIndex(1)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上： 421 422 423 424第二次按TAB键，焦点切换到tabIndex(2)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上： 425 426 427 428第三次按TAB键，焦点切换到tabIndex(3)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上： 429 430 431 432点击绑定了focusOnTouch的组件，组件自身获焦，焦点框被清除，再按下Tab键显示焦点框： 433 434 435 436### 示例2（设置指定组件获焦） 437 438该示例通过配置focusControl.requestFocus使指定组件获取焦点。 439 440> **说明：** 441> 442> 直接使用focusControl可能导致实例不明确的问题，建议使用[getUIContext](../js-apis-arkui-UIContext.md#uicontext)获取UIContext实例，并使用[getFocusController](../js-apis-arkui-UIContext.md#getfocuscontroller12)获取绑定实例的focusControl。 443 444```ts 445// requestFocus.ets 446@Entry 447@Component 448struct RequestFocusExample { 449 @State idList: string[] = ['A', 'B', 'C', 'D', 'E', 'F', 'LastPageId'] 450 @State selectId: string = 'LastPageId' 451 452 build() { 453 Column({ space:20 }){ 454 Row({space: 5}) { 455 Button("id: " + this.idList[0] + " focusable(false)") 456 .width(200).height(70).fontColor(Color.White) 457 .id(this.idList[0]) 458 .focusable(false) 459 Button("id: " + this.idList[1]) 460 .width(200).height(70).fontColor(Color.White) 461 .id(this.idList[1]) 462 } 463 Row({space: 5}) { 464 Button("id: " + this.idList[2]) 465 .width(200).height(70).fontColor(Color.White) 466 .id(this.idList[2]) 467 Button("id: " + this.idList[3]) 468 .width(200).height(70).fontColor(Color.White) 469 .id(this.idList[3]) 470 } 471 Row({space: 5}) { 472 Button("id: " + this.idList[4]) 473 .width(200).height(70).fontColor(Color.White) 474 .id(this.idList[4]) 475 Button("id: " + this.idList[5]) 476 .width(200).height(70).fontColor(Color.White) 477 .id(this.idList[5]) 478 } 479 Row({space: 5}) { 480 Select([{value: this.idList[0]}, 481 {value: this.idList[1]}, 482 {value: this.idList[2]}, 483 {value: this.idList[3]}, 484 {value: this.idList[4]}, 485 {value: this.idList[5]}, 486 {value: this.idList[6]}]) 487 .value(this.selectId) 488 .onSelect((index: number) => { 489 this.selectId = this.idList[index] 490 }) 491 Button("RequestFocus") 492 .width(200).height(70).fontColor(Color.White) 493 .onClick(() => { 494 // 建议使用this.getUIContext().getFocusController().requestFocus() 495 let res = focusControl.requestFocus(this.selectId) // 使选中的this.selectId的组件获焦 496 if (res) { 497 this.getUIContext().getPromptAction().showToast({message: 'Request success'}) 498 } else { 499 this.getUIContext().getPromptAction().showToast({message: 'Request failed'}) 500 } 501 }) 502 } 503 }.width('100%').margin({ top:20 }) 504 } 505} 506``` 507 508示意图： 509 510按下TAB键，激活焦点态显示。 511申请不存在的组件获焦： 512 513 514 515申请不可获焦的组件获焦： 516 517 518 519申请存在且可获焦的组件获焦： 520 521 522 523### 示例3（设置焦点框样式） 524 525该示例通过配置focusBox修改组件的焦点框样式。 526 527```ts 528import { ColorMetrics, LengthMetrics } from '@kit.ArkUI' 529 530@Entry 531@Component 532struct RequestFocusExample { 533 build() { 534 Column({ space: 30 }) { 535 Button("small black focus box") 536 .focusBox({ 537 margin: new LengthMetrics(0), 538 strokeColor: ColorMetrics.rgba(0, 0, 0), 539 }) 540 Button("large red focus box") 541 .focusBox({ 542 margin: LengthMetrics.px(20), 543 strokeColor: ColorMetrics.rgba(255, 0, 0), 544 strokeWidth: LengthMetrics.px(10) 545 }) 546 } 547 .alignItems(HorizontalAlign.Center) 548 .width('100%') 549 } 550} 551``` 552 553 554 555 556### 示例4（设置焦点组走焦） 557 558该示例通过配置focusScopePriority可以使绑定的组件成为所属容器首次获焦时的焦点，配置focusScopeId可以使绑定的容器组件组件成为焦点组。 559 560```ts 561// focusTest.ets 562@Entry 563@Component 564struct FocusableExample { 565 @State inputValue: string = '' 566 567 build() { 568 Scroll() { 569 Row({ space: 20 }) { 570 Column({ space: 20 }) { // 标记为Column1 571 Column({ space: 5 }) { 572 Button('Group1') 573 .width(165) 574 .height(40) 575 .fontColor(Color.White) 576 Row({ space: 5 }) { 577 Button() 578 .width(80) 579 .height(40) 580 .fontColor(Color.White) 581 Button() 582 .width(80) 583 .height(40) 584 .fontColor(Color.White) 585 } 586 Row({ space: 5 }) { 587 Button() 588 .width(80) 589 .height(40) 590 .fontColor(Color.White) 591 Button() 592 .width(80) 593 .height(40) 594 .fontColor(Color.White) 595 } 596 }.borderWidth(2).borderColor(Color.Red).borderStyle(BorderStyle.Dashed) 597 Column({ space: 5 }) { 598 Button('Group2') 599 .width(165) 600 .height(40) 601 .fontColor(Color.White) 602 Row({ space: 5 }) { 603 Button() 604 .width(80) 605 .height(40) 606 .fontColor(Color.White) 607 Button() 608 .width(80) 609 .height(40) 610 .fontColor(Color.White) 611 .focusScopePriority('ColumnScope1', FocusPriority.PRIOR) // Column1首次获焦时获焦 612 } 613 Row({ space: 5 }) { 614 Button() 615 .width(80) 616 .height(40) 617 .fontColor(Color.White) 618 Button() 619 .width(80) 620 .height(40) 621 .fontColor(Color.White) 622 } 623 }.borderWidth(2).borderColor(Color.Green).borderStyle(BorderStyle.Dashed) 624 } 625 .focusScopeId('ColumnScope1') 626 Column({ space: 5 }) { // 标记为Column2 627 TextInput({placeholder: 'input', text: this.inputValue}) 628 .onChange((value: string) => { 629 this.inputValue = value 630 }) 631 .width(156) 632 Button('Group3') 633 .width(165) 634 .height(40) 635 .fontColor(Color.White) 636 Row({ space: 5 }) { 637 Button() 638 .width(80) 639 .height(40) 640 .fontColor(Color.White) 641 Button() 642 .width(80) 643 .height(40) 644 .fontColor(Color.White) 645 } 646 Button() 647 .width(165) 648 .height(40) 649 .fontColor(Color.White) 650 .focusScopePriority('ColumnScope2', FocusPriority.PREVIOUS) // Column2获焦时获焦 651 Row({ space: 5 }) { 652 Button() 653 .width(80) 654 .height(40) 655 .fontColor(Color.White) 656 Button() 657 .width(80) 658 .height(40) 659 .fontColor(Color.White) 660 } 661 Button() 662 .width(165) 663 .height(40) 664 .fontColor(Color.White) 665 Row({ space: 5 }) { 666 Button() 667 .width(80) 668 .height(40) 669 .fontColor(Color.White) 670 Button() 671 .width(80) 672 .height(40) 673 .fontColor(Color.White) 674 } 675 }.borderWidth(2).borderColor(Color.Orange).borderStyle(BorderStyle.Dashed) 676 .focusScopeId('ColumnScope2', true) // Column2为焦点组 677 }.alignItems(VerticalAlign.Top) 678 } 679 } 680} 681``` 682 683### 示例5（设置tab走焦停留） 684 685该示例通过配置tabstop实现使用tab走焦停留在组件上。 686 687```ts 688import { ColorMetrics, LengthMetrics } from '@kit.ArkUI' 689 690@Entry 691@Component 692struct TabStop { 693 build() { 694 Column({ space: 20 }) { 695 Column({ space: 20 }) { 696 Column({ space: 20 }) { 697 Row({ space: 5 }) { 698 Button("button 1") 699 .width(200).height(70).fontColor(Color.White) 700 .focusBox({ 701 margin: LengthMetrics.px(20), 702 strokeColor: ColorMetrics.rgba(23, 169, 141), 703 strokeWidth: LengthMetrics.px(10) 704 }) 705 } 706 Row({ space: 5 }) { 707 Button("button 2") 708 .width(200).height(70).fontColor(Color.White) 709 .focusBox({ 710 margin: LengthMetrics.px(20), 711 strokeColor: ColorMetrics.rgba(23, 169, 141), 712 strokeWidth: LengthMetrics.px(10) 713 }) 714 } 715 }.width('80%').margin({ top: 30 }).borderColor(Color.Black) 716 }.width('95%').margin({ top: 60 }).borderColor(Color.Black) 717 Column({ space: 20 }) { 718 Column({ space: 20 }) { 719 Row({ space: 5 }) { 720 Button("button 3") 721 .width(200) 722 .height('70%') 723 .fontColor(Color.White) 724 .focusBox({ 725 margin: LengthMetrics.px(20), 726 strokeColor: ColorMetrics.rgba(23, 169, 141), 727 strokeWidth: LengthMetrics.px(10) 728 }) 729 .margin({ top: 15 }) 730 } 731 } 732 .width('80%') 733 .height('120') 734 .borderColor(Color.Black) 735 .margin({ top: 10 }) 736 .tabStop(true) 737 .focusBox({ 738 margin: LengthMetrics.px(20), 739 strokeColor: ColorMetrics.rgba(23, 169, 141), 740 strokeWidth: LengthMetrics.px(10) 741 }) 742 .borderWidth(1) 743 }.width('95%').margin({ top: 50 }).borderColor(Color.Black) 744 } 745 } 746} 747``` 748示意图： 749 750连续按下两次TAB键时，焦点转移到button2上。 751 752 753 754接着按下TAB键，焦点转移到配置了tabStop的组件。 755 756 757 758再按下Enter键，焦点转移至内部button3上。 759 760 761 762再按下ESC键，焦点转移到配置了tabStop的组件上。 763 764 765 766再按下TAB键，焦点循环走焦到button1上。 767 768 769 770### 示例6（设置自定义走焦） 771 772该示例通过配置nextFocus实现自定义走焦规则。 773如果不配置nextFocus，默认点击tab的走焦顺序：M->A->B->C；配置了nextFocus以后,走焦顺序变更为：M->D->F->B。 774 775```ts 776class MyButtonModifier implements AttributeModifier<ButtonAttribute> { 777 applyNormalAttribute(instance: ButtonAttribute): void { 778 instance.id('M') 779 instance.nextFocus({forward: 'D', up: 'C', down: 'D'}) 780 } 781} 782 783@Entry 784@Component 785struct Index { 786 @State modifier: MyButtonModifier = new MyButtonModifier() 787 @State idList: string[] = ['A', 'B', 'C', 'D', 'E', 'F'] 788 789 build() { 790 Column({space: 10}) { 791 Row({space: 10}) { 792 Button("id: M") 793 .attributeModifier(this.modifier) 794 Button("id: " + this.idList[0]) 795 .id(this.idList[0]) 796 .nextFocus({forward: 'C', backward: 'M', up: 'E', right: 'F', down: 'B', left: 'D'}); 797 Button("id: " + this.idList[1]) 798 .id(this.idList[1]) 799 } 800 Column({space: 10}) { 801 Button("id: " + this.idList[2]) 802 .id(this.idList[2]); 803 Button("id: " + this.idList[3]) 804 .id(this.idList[3]) 805 .nextFocus({forward: 'F'}); 806 } 807 Row({space: 10}) { 808 Button("id: " + this.idList[4]) 809 .id(this.idList[4]); 810 Button("id: " + this.idList[5]) 811 .id(this.idList[5]) 812 .nextFocus({forward: 'B'}); 813 } 814 } 815 } 816} 817``` 818 819
