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