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 | 是 | 设置当前组件是否可以获焦。<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 | 是 | 设置当前组件是否为当前组件所在容器获焦时的默认焦点，仅在初次创建容器节点第一次获焦时生效。<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 | 是 | 设置当前容器组件是否为走焦可停留容器。<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## 示例 251 252### 示例1（设置组件获焦和走焦的效果） 253 254该示例通过配置defaultFocus可以使绑定的组件成为页面创建后首次获焦的焦点，配置groupDefaultFocus可以使绑定的组件成为tabIndex容器创建后首次获焦的焦点，配置focusOnTouch可以使绑定的组件点击后立即获焦。 255 256```ts 257// focusTest.ets 258@Entry 259@Component 260struct FocusableExample { 261 @State inputValue: string = '' 262 263 build() { 264 Scroll() { 265 Row({ space: 20 }) { 266 Column({ space: 20 }) { 267 Column({ space: 5 }) { 268 Button('Group1') 269 .width(165) 270 .height(40) 271 .fontColor(Color.White) 272 .focusOnTouch(true) // 该Button组件点击后可获焦 273 Row({ space: 5 }) { 274 Button() 275 .width(80) 276 .height(40) 277 .fontColor(Color.White) 278 Button() 279 .width(80) 280 .height(40) 281 .fontColor(Color.White) 282 .focusOnTouch(true) // 该Button组件点击后可获焦 283 } 284 Row({ space: 5 }) { 285 Button() 286 .width(80) 287 .height(40) 288 .fontColor(Color.White) 289 Button() 290 .width(80) 291 .height(40) 292 .fontColor(Color.White) 293 } 294 }.borderWidth(2).borderColor(Color.Red).borderStyle(BorderStyle.Dashed) 295 .tabIndex(1) // 该Column组件为按TAB键走焦的第一个获焦的组件 296 Column({ space: 5 }) { 297 Button('Group2') 298 .width(165) 299 .height(40) 300 .fontColor(Color.White) 301 Row({ space: 5 }) { 302 Button() 303 .width(80) 304 .height(40) 305 .fontColor(Color.White) 306 Button() 307 .width(80) 308 .height(40) 309 .fontColor(Color.White) 310 .groupDefaultFocus(true) // 该Button组件上级Column组件获焦时获焦 311 } 312 Row({ space: 5 }) { 313 Button() 314 .width(80) 315 .height(40) 316 .fontColor(Color.White) 317 Button() 318 .width(80) 319 .height(40) 320 .fontColor(Color.White) 321 } 322 }.borderWidth(2).borderColor(Color.Green).borderStyle(BorderStyle.Dashed) 323 .tabIndex(2) // 该Column组件为按TAB键走焦的第二个获焦的组件 324 } 325 Column({ space: 5 }) { 326 TextInput({placeholder: 'input', text: this.inputValue}) 327 .onChange((value: string) => { 328 this.inputValue = value 329 }) 330 .width(156) 331 .defaultFocus(true) // 该TextInput组件为页面的初始默认焦点 332 Button('Group3') 333 .width(165) 334 .height(40) 335 .fontColor(Color.White) 336 Row({ space: 5 }) { 337 Button() 338 .width(80) 339 .height(40) 340 .fontColor(Color.White) 341 Button() 342 .width(80) 343 .height(40) 344 .fontColor(Color.White) 345 } 346 Button() 347 .width(165) 348 .height(40) 349 .fontColor(Color.White) 350 Row({ space: 5 }) { 351 Button() 352 .width(80) 353 .height(40) 354 .fontColor(Color.White) 355 Button() 356 .width(80) 357 .height(40) 358 .fontColor(Color.White) 359 } 360 Button() 361 .width(165) 362 .height(40) 363 .fontColor(Color.White) 364 Row({ space: 5 }) { 365 Button() 366 .width(80) 367 .height(40) 368 .fontColor(Color.White) 369 Button() 370 .width(80) 371 .height(40) 372 .fontColor(Color.White) 373 } 374 }.borderWidth(2).borderColor(Color.Orange).borderStyle(BorderStyle.Dashed) 375 .tabIndex(3) // 该Column组件为按TAB键走焦的第三个获焦的组件 376 }.alignItems(VerticalAlign.Top) 377 } 378 } 379} 380``` 381示意图： 382 383首次进入，焦点默认在defaultFocus绑定的TextInput组件上： 384 385 386 387首次按TAB键，焦点切换到tabIndex(1)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上： 388 389 390 391第二次按TAB键，焦点切换到tabIndex(2)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上： 392 393 394 395第三次按TAB键，焦点切换到tabIndex(3)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上： 396 397 398 399点击绑定了focusOnTouch的组件，组件自身获焦，焦点框被清除，再按下Tab键显示焦点框： 400 401 402 403### 示例2（设置指定组件获焦） 404 405该示例通过配置focusControl.requestFocus使指定组件获取焦点。 406 407> **说明：** 408> 409> 直接使用focusControl可能导致实例不明确的问题，建议使用[getUIContext](../js-apis-arkui-UIContext.md#uicontext)获取UIContext实例，并使用[getFocusController](../js-apis-arkui-UIContext.md#getfocuscontroller12)获取绑定实例的focusControl。 410 411```ts 412// requestFocus.ets 413@Entry 414@Component 415struct RequestFocusExample { 416 @State idList: string[] = ['A', 'B', 'C', 'D', 'E', 'F', 'LastPageId'] 417 @State selectId: string = 'LastPageId' 418 419 build() { 420 Column({ space:20 }){ 421 Row({space: 5}) { 422 Button("id: " + this.idList[0] + " focusable(false)") 423 .width(200).height(70).fontColor(Color.White) 424 .id(this.idList[0]) 425 .focusable(false) 426 Button("id: " + this.idList[1]) 427 .width(200).height(70).fontColor(Color.White) 428 .id(this.idList[1]) 429 } 430 Row({space: 5}) { 431 Button("id: " + this.idList[2]) 432 .width(200).height(70).fontColor(Color.White) 433 .id(this.idList[2]) 434 Button("id: " + this.idList[3]) 435 .width(200).height(70).fontColor(Color.White) 436 .id(this.idList[3]) 437 } 438 Row({space: 5}) { 439 Button("id: " + this.idList[4]) 440 .width(200).height(70).fontColor(Color.White) 441 .id(this.idList[4]) 442 Button("id: " + this.idList[5]) 443 .width(200).height(70).fontColor(Color.White) 444 .id(this.idList[5]) 445 } 446 Row({space: 5}) { 447 Select([{value: this.idList[0]}, 448 {value: this.idList[1]}, 449 {value: this.idList[2]}, 450 {value: this.idList[3]}, 451 {value: this.idList[4]}, 452 {value: this.idList[5]}, 453 {value: this.idList[6]}]) 454 .value(this.selectId) 455 .onSelect((index: number) => { 456 this.selectId = this.idList[index] 457 }) 458 Button("RequestFocus") 459 .width(200).height(70).fontColor(Color.White) 460 .onClick(() => { 461 // 建议使用this.getUIContext().getFocusController().requestFocus() 462 let res = focusControl.requestFocus(this.selectId) // 使选中的this.selectId的组件获焦 463 if (res) { 464 this.getUIContext().getPromptAction().showToast({message: 'Request success'}) 465 } else { 466 this.getUIContext().getPromptAction().showToast({message: 'Request failed'}) 467 } 468 }) 469 } 470 }.width('100%').margin({ top:20 }) 471 } 472} 473``` 474 475示意图： 476 477按下TAB键，激活焦点态显示。 478申请不存在的组件获焦： 479 480 481 482申请不可获焦的组件获焦： 483 484 485 486申请存在且可获焦的组件获焦： 487 488 489 490### 示例3（设置焦点框样式） 491 492该示例通过配置focusBox修改组件的焦点框样式。 493 494```ts 495import { ColorMetrics, LengthMetrics } from '@kit.ArkUI' 496 497@Entry 498@Component 499struct RequestFocusExample { 500 build() { 501 Column({ space: 30 }) { 502 Button("small black focus box") 503 .focusBox({ 504 margin: new LengthMetrics(0), 505 strokeColor: ColorMetrics.rgba(0, 0, 0), 506 }) 507 Button("large red focus box") 508 .focusBox({ 509 margin: LengthMetrics.px(20), 510 strokeColor: ColorMetrics.rgba(255, 0, 0), 511 strokeWidth: LengthMetrics.px(10) 512 }) 513 } 514 .alignItems(HorizontalAlign.Center) 515 .width('100%') 516 } 517} 518``` 519 520 521 522 523### 示例4（设置焦点组走焦） 524 525该示例通过配置focusScopePriority可以使绑定的组件成为所属容器首次获焦时的焦点，配置focusScopeId可以使绑定的容器组件组件成为焦点组。 526 527```ts 528// focusTest.ets 529@Entry 530@Component 531struct FocusableExample { 532 @State inputValue: string = '' 533 534 build() { 535 Scroll() { 536 Row({ space: 20 }) { 537 Column({ space: 20 }) { // 标记为Column1 538 Column({ space: 5 }) { 539 Button('Group1') 540 .width(165) 541 .height(40) 542 .fontColor(Color.White) 543 Row({ space: 5 }) { 544 Button() 545 .width(80) 546 .height(40) 547 .fontColor(Color.White) 548 Button() 549 .width(80) 550 .height(40) 551 .fontColor(Color.White) 552 } 553 Row({ space: 5 }) { 554 Button() 555 .width(80) 556 .height(40) 557 .fontColor(Color.White) 558 Button() 559 .width(80) 560 .height(40) 561 .fontColor(Color.White) 562 } 563 }.borderWidth(2).borderColor(Color.Red).borderStyle(BorderStyle.Dashed) 564 Column({ space: 5 }) { 565 Button('Group2') 566 .width(165) 567 .height(40) 568 .fontColor(Color.White) 569 Row({ space: 5 }) { 570 Button() 571 .width(80) 572 .height(40) 573 .fontColor(Color.White) 574 Button() 575 .width(80) 576 .height(40) 577 .fontColor(Color.White) 578 .focusScopePriority('ColumnScope1', FocusPriority.PRIOR) // Column1首次获焦时获焦 579 } 580 Row({ space: 5 }) { 581 Button() 582 .width(80) 583 .height(40) 584 .fontColor(Color.White) 585 Button() 586 .width(80) 587 .height(40) 588 .fontColor(Color.White) 589 } 590 }.borderWidth(2).borderColor(Color.Green).borderStyle(BorderStyle.Dashed) 591 } 592 .focusScopeId('ColumnScope1') 593 Column({ space: 5 }) { // 标记为Column2 594 TextInput({placeholder: 'input', text: this.inputValue}) 595 .onChange((value: string) => { 596 this.inputValue = value 597 }) 598 .width(156) 599 Button('Group3') 600 .width(165) 601 .height(40) 602 .fontColor(Color.White) 603 Row({ space: 5 }) { 604 Button() 605 .width(80) 606 .height(40) 607 .fontColor(Color.White) 608 Button() 609 .width(80) 610 .height(40) 611 .fontColor(Color.White) 612 } 613 Button() 614 .width(165) 615 .height(40) 616 .fontColor(Color.White) 617 .focusScopePriority('ColumnScope2', FocusPriority.PREVIOUS) // Column2获焦时获焦 618 Row({ space: 5 }) { 619 Button() 620 .width(80) 621 .height(40) 622 .fontColor(Color.White) 623 Button() 624 .width(80) 625 .height(40) 626 .fontColor(Color.White) 627 } 628 Button() 629 .width(165) 630 .height(40) 631 .fontColor(Color.White) 632 Row({ space: 5 }) { 633 Button() 634 .width(80) 635 .height(40) 636 .fontColor(Color.White) 637 Button() 638 .width(80) 639 .height(40) 640 .fontColor(Color.White) 641 } 642 }.borderWidth(2).borderColor(Color.Orange).borderStyle(BorderStyle.Dashed) 643 .focusScopeId('ColumnScope2', true) // Column2为焦点组 644 }.alignItems(VerticalAlign.Top) 645 } 646 } 647} 648``` 649 650### 示例5（设置tab走焦停留） 651 652该示例通过配置tabstop实现使用tab走焦停留在组件上。 653 654```ts 655import { ColorMetrics, LengthMetrics } from '@kit.ArkUI' 656 657@Entry 658@Component 659struct TabStop { 660 build() { 661 Column({ space: 20 }) { 662 Column({ space: 20 }) { 663 Column({ space: 20 }) { 664 Row({ space: 5 }) { 665 Button("button 1") 666 .width(200).height(70).fontColor(Color.White) 667 .focusBox({ 668 margin: LengthMetrics.px(20), 669 strokeColor: ColorMetrics.rgba(23, 169, 141), 670 strokeWidth: LengthMetrics.px(10) 671 }) 672 } 673 Row({ space: 5 }) { 674 Button("button 2") 675 .width(200).height(70).fontColor(Color.White) 676 .focusBox({ 677 margin: LengthMetrics.px(20), 678 strokeColor: ColorMetrics.rgba(23, 169, 141), 679 strokeWidth: LengthMetrics.px(10) 680 }) 681 } 682 }.width('80%').margin({ top: 30 }).borderColor(Color.Black) 683 }.width('95%').margin({ top: 60 }).borderColor(Color.Black) 684 Column({ space: 20 }) { 685 Column({ space: 20 }) { 686 Row({ space: 5 }) { 687 Button("button 3") 688 .width(200) 689 .height('70%') 690 .fontColor(Color.White) 691 .focusBox({ 692 margin: LengthMetrics.px(20), 693 strokeColor: ColorMetrics.rgba(23, 169, 141), 694 strokeWidth: LengthMetrics.px(10) 695 }) 696 .margin({ top: 15 }) 697 } 698 } 699 .width('80%') 700 .height('120') 701 .borderColor(Color.Black) 702 .margin({ top: 10 }) 703 .tabStop(true) 704 .focusBox({ 705 margin: LengthMetrics.px(20), 706 strokeColor: ColorMetrics.rgba(23, 169, 141), 707 strokeWidth: LengthMetrics.px(10) 708 }) 709 .borderWidth(1) 710 }.width('95%').margin({ top: 50 }).borderColor(Color.Black) 711 } 712 } 713} 714``` 715示意图： 716 717连续按下两次TAB键时，焦点转移到button2上。 718 719 720 721接着按下TAB键，焦点转移到配置了tabStop的组件。 722 723 724 725再按下Enter键，焦点转移至内部button3上。 726 727 728 729再按下ESC键，焦点转移到配置了tabStop的组件上。 730 731 732 733再按下TAB键，焦点循环走焦到button1上。 734 735 736
