鸿蒙NEXT开发：ArkTS组件-通用属性（焦点控制）

自定义组件的走焦效果，可设置组件是否走焦和具体的走焦顺序，tab键或者方向键切换焦点。

奋斗的小野猪

1022人浏览 · 2025-03-25 13:57:22

奋斗的小野猪 · 2025-03-25 13:57:22 发布

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

焦点控制

自定义组件的走焦效果，可设置组件是否走焦和具体的走焦顺序，tab键或者方向键切换焦点。

说明

从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

自定义组件无获焦能力，当设置focusable、enabled等属性为false，或者设置visibility属性为Hidden、None时，也不影响其子组件的获焦。

组件主动获取焦点不受窗口焦点的控制。

焦点开发参考焦点开发指南。

focusable

focusable(value: boolean)

设置当前组件是否可以获焦。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	设置当前组件是否可以获焦。说明：存在默认交互逻辑的组件例如Button、TextInput等，默认即为可获焦，Text、Image等组件则默认状态为不可获焦。不可获焦状态下，无法触发焦点事件。

参数名

类型

必填

说明

value

boolean

是

设置当前组件是否可以获焦。

说明：

存在默认交互逻辑的组件例如Button、TextInput等，默认即为可获焦，Text、Image等组件则默认状态为不可获焦。不可获焦状态下，无法触发焦点事件。

tabIndex9+

tabIndex(index: number)

自定义组件tab键走焦能力。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
index	number	是	自定义组件tab键走焦能力。若有配置了tabIndex大于0的组件，则tab键走焦只会在tabIndex大于0的组件内按照tabIndex的值从小到大并循环依次走焦。若没有配置tabIndex大于0的组件，则tabIndex等于0的组件按照组件预设的走焦规则走焦。 UiExtension组件未适配tabIndex，在含有UiExtension组件的页面使用tabIndex会导致走焦错乱。 - tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素。 - tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素。默认值：0 说明： tabIndex与focusScopeId不能混用。

参数名

类型

必填

说明

index

number

是

自定义组件tab键走焦能力。若有配置了tabIndex大于0的组件，则tab键走焦只会在tabIndex大于0的组件内按照tabIndex的值从小到大并循环依次走焦。若没有配置tabIndex大于0的组件，则tabIndex等于0的组件按照组件预设的走焦规则走焦。

UiExtension组件未适配tabIndex，在含有UiExtension组件的页面使用tabIndex会导致走焦错乱。

- tabIndex >= 0：表示元素是可聚焦的，并且可以通过tab键走焦来访问到该元素。

- tabIndex < 0（通常是tabIndex = -1）：表示元素是可聚焦的，但是不能通过tab键走焦来访问到该元素。

默认值：0

说明：

tabIndex与focusScopeId不能混用。

defaultFocus9+

defaultFocus(value: boolean)

设置当前组件是否为当前页面上的默认焦点。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	设置当前组件是否为当前页面上的默认焦点，仅在初次创建的页面第一次进入时生效。默认值：false 说明：值为true则表示为默认焦点，值为false无效。若页面内无任何组件设置defaultFocus(true)，API version 11及之前，页面的默认焦点是当前页面上首个可获焦的非容器组件，API version 11之后，页面的默认焦点就是页面的根容器。若某页面内有多个组件设置了defaultFocus(true)，则以组件树深度遍历找到的第一个组件为默认焦点。

参数名

类型

必填

说明

value

boolean

是

设置当前组件是否为当前页面上的默认焦点，仅在初次创建的页面第一次进入时生效。

默认值：false

说明：

值为true则表示为默认焦点，值为false无效。

若页面内无任何组件设置defaultFocus(true)，API version 11及之前，页面的默认焦点是当前页面上首个可获焦的非容器组件，API version 11之后，页面的默认焦点就是页面的根容器。

若某页面内有多个组件设置了defaultFocus(true)，则以组件树深度遍历找到的第一个组件为默认焦点。

groupDefaultFocus9+

groupDefaultFocus(value: boolean)

设置当前组件是否为当前组件所在容器获焦时的默认焦点。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	设置当前组件是否为当前组件所在容器获焦时的默认焦点，仅在初次创建容器节点第一次获焦时生效。默认值：false 说明：必须与tabIndex联合使用，当某个容器设置了tabIndex，且容器内某子组件或容器自身设置了groupDefaultFocus(true)，当该容器首次TAB键获焦时，会自动将焦点转移至该指定的组件上。若容器内（包含容器本身）有多个组件设置了groupDefaultFocus(true)，则以组件树深度遍历找到的第一个组件为最终结果。

参数名

类型

必填

说明

value

boolean

是

设置当前组件是否为当前组件所在容器获焦时的默认焦点，仅在初次创建容器节点第一次获焦时生效。

默认值：false

说明：

必须与tabIndex联合使用，当某个容器设置了tabIndex，且容器内某子组件或容器自身设置了groupDefaultFocus(true)，当该容器首次TAB键获焦时，会自动将焦点转移至该指定的组件上。若容器内（包含容器本身）有多个组件设置了groupDefaultFocus(true)，则以组件树深度遍历找到的第一个组件为最终结果。

focusOnTouch9+

focusOnTouch(value: boolean)

设置当前组件是否支持点击获焦能力。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	设置当前组件是否支持点击获焦能力。默认值：false 说明：仅在组件可点击时才能正常获取焦点。

参数名

类型

必填

说明

value

boolean

是

设置当前组件是否支持点击获焦能力。

默认值：false

说明：

仅在组件可点击时才能正常获取焦点。

focusBox12+

focusBox(style: FocusBoxStyle): T

设置当前组件系统焦点框样式。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
style	FocusBoxStyle	是	设置当前组件系统焦点框样式。说明：该样式仅影响走焦状态下展示了系统焦点框的组件。

参数名

类型

必填

说明

style

FocusBoxStyle

是

设置当前组件系统焦点框样式。

说明：

该样式仅影响走焦状态下展示了系统焦点框的组件。

focusControl9+

焦点控制模块

元服务API： 从API version 11开始，该接口支持在元服务中使用。

requestFocus9+

requestFocus(value: string): boolean

方法语句中可使用的全局接口，调用此接口可以主动让焦点转移至参数指定的组件上。非当前帧生效，在下一帧才生效，建议使用FocusController中的requestFocus。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

参数：

名称	类型	必填	描述
value	string	是	目标组件使用接口key(value: string)或id(value: string)绑定的字符串。

返回值：

类型	说明
boolean	返回是否成功给目标组件申请到焦点。若参数指向的目标组件存在，且目标组件可获焦，则返回true，否则返回false。

说明

支持焦点控制的组件：TextInput、TextArea、Search、Button、Text、Image、List、Grid。焦点事件当前仅支持在真机上显示运行效果。

FocusBoxStyle12+对象说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。

名称	参数类型	必填	描述
margin	LengthMetrics	否	焦点框相对组件边缘的距离。正数代表外侧，负数代表内侧。不支持百分比。
strokeColor	ColorMetrics	否	焦点框颜色。
strokeWidth	LengthMetrics	否	焦点框宽度。不支持负数与百分比。

名称

参数类型

必填

描述

margin

LengthMetrics

否

焦点框相对组件边缘的距离。

正数代表外侧，负数代表内侧。不支持百分比。

strokeColor

ColorMetrics

否

焦点框颜色。

strokeWidth

LengthMetrics

否

焦点框宽度。

不支持负数与百分比。

focusScopePriority12+

focusScopePriority(scopeId: string, priority?: FocusPriority): T

设置当前组件在指定容器内获焦的优先级。需要配合focusScopeId一起使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
scopeId	string	是	当前组件设置的获焦优先级生效的容器组件的id标识。说明： 1.当前组件必须在scopeId所标识的容器内或者当前组件所属容器在scopeId所标识的容器内。 2.组件不可重复设置多个优先级。 3.设置了focusScopeId的容器组件不可设置优先级。
priority	FocusPriority	否	获焦优先级。说明： priority不设置则组件为默认AUTO优先级。优先级对走焦以及获焦组件的影响： 1.容器整体获焦（层级页面切换/焦点切换到焦点组/容器组件使用requestFocus申请焦点）时，若容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由容器内上次获焦的组件获焦； 2.容器非整体获焦（非焦点组场景下使用tab键/方向键走焦）时，若容器为首次获焦，则容器内优先级最高的组件获焦，若容器非首次获焦，不考虑优先级按照位置顺序走焦。

参数名

类型

必填

说明

scopeId

string

是

当前组件设置的获焦优先级生效的容器组件的id标识。

说明：

1.当前组件必须在scopeId所标识的容器内或者当前组件所属容器在scopeId所标识的容器内。

2.组件不可重复设置多个优先级。

3.设置了focusScopeId的容器组件不可设置优先级。

priority

FocusPriority

否

获焦优先级。

说明：

priority不设置则组件为默认AUTO优先级。

优先级对走焦以及获焦组件的影响：

1.容器整体获焦（层级页面切换/焦点切换到焦点组/容器组件使用requestFocus申请焦点）时，若容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由容器内上次获焦的组件获焦；

2.容器非整体获焦（非焦点组场景下使用tab键/方向键走焦）时，若容器为首次获焦，则容器内优先级最高的组件获焦，若容器非首次获焦，不考虑优先级按照位置顺序走焦。

FocusPriority12+

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	描述
AUTO	默认的优先级，缺省时组件的获焦优先级。
PRIOR	容器内优先获焦的优先级。优先级高于AUTO。
PREVIOUS	上一次容器整体失焦时获焦节点的优先级。优先级高于PRIOR。

focusScopeId12+

focusScopeId(id: string, isGroup?: boolean)

设置当前容器组件的id标识，设置当前容器组件是否为焦点组。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
id	string	是	设置当前容器组件的id标识。说明：单个层级页面下，id标识全局唯一，不可重复。
isGroup	boolean	否	设置当前容器组件是否为焦点组。说明：焦点组不可嵌套，不可重复配置。焦点组不能和tabIndex混用。配置焦点组的目的时使得容器及容器内的元素可以按照焦点组规则走焦。焦点组走焦规则： 1.焦点组容器内只能通过方向键走焦，tab键会使焦点跳出焦点组容器。 2.通过方向键使焦点从焦点组容器外切换到焦点组容器内时，若焦点组容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由焦点组容器内上次获焦的组件获焦。

参数名

类型

必填

说明

string

是

设置当前容器组件的id标识。

说明：

单个层级页面下，id标识全局唯一，不可重复。

isGroup

boolean

否

设置当前容器组件是否为焦点组。

说明：

焦点组不可嵌套，不可重复配置。

焦点组不能和tabIndex混用。

配置焦点组的目的时使得容器及容器内的元素可以按照焦点组规则走焦。焦点组走焦规则：

1.焦点组容器内只能通过方向键走焦，tab键会使焦点跳出焦点组容器。

2.通过方向键使焦点从焦点组容器外切换到焦点组容器内时，若焦点组容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由焦点组容器内上次获焦的组件获焦。

focusScopeId14+

focusScopeId(id: string, isGroup?: boolean, arrowStepOut?: boolean)

设置当前容器组件的id标识，设置当前容器组件是否为焦点组。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
id	string	是	设置当前容器组件的id标识。说明：单个层级页面下，id标识全局唯一，不可重复。元服务API：从API version 12开始，该接口支持在元服务中使用。
isGroup	boolean	否	设置当前容器组件是否为焦点组。说明：焦点组不可嵌套，不可重复配置。焦点组不能和tabIndex混用。配置焦点组的目的时使得容器及容器内的元素可以按照焦点组规则走焦。焦点组走焦规则： 1.焦点组容器内只能通过方向键走焦，tab键会使焦点跳出焦点组容器。 2.通过方向键使焦点从焦点组容器外切换到焦点组容器内时，若焦点组容器内存在优先级为PREVIOUS的组件，则优先级为PREVIOUS的组件获焦，否则，由焦点组容器内上次获焦的组件获焦。元服务API：从API version 12开始，该接口支持在元服务中使用。
arrowStepOut14+	boolean	否	设置能否使用方向键走焦出当前焦点组。元服务API：从API version 14开始，该接口支持在元服务中使用。

参数名

类型

必填

说明

string

是

设置当前容器组件的id标识。

说明：

单个层级页面下，id标识全局唯一，不可重复。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

isGroup

boolean

否

设置当前容器组件是否为焦点组。

说明：

焦点组不可嵌套，不可重复配置。

焦点组不能和tabIndex混用。

配置焦点组的目的时使得容器及容器内的元素可以按照焦点组规则走焦。焦点组走焦规则：

1.焦点组容器内只能通过方向键走焦，tab键会使焦点跳出焦点组容器。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

arrowStepOut14+

boolean

否

设置能否使用方向键走焦出当前焦点组。

元服务API： 从API version 14开始，该接口支持在元服务中使用。

tabStop14+

tabStop(isTabStop: boolean) :T

设置当前容器组件的tabStop，可决定在走焦时焦点是否会停留在当前容器。

元服务API： 从API version 14开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
isTabStop	boolean	是	设置当前容器组件是否为走焦可停留容器。说明： 1.配置tabStop需要保障是容器组件且有可获焦的孩子组件，默认容器组件不能直接获焦。 2.通过requestFocus请求焦点，如果是容器组件且配置tabStop，焦点能够停留在容器组件，如果未配置tabStop，即使整条焦点链上有配置了tabStop的组件，该组件依然能获取到焦点。 3.配置tabStop的容器不允许嵌套超过2层。 tabStop走焦规则： 1.通过tab键和方向键走焦，焦点会停留在配置了tabStop的组件上，如果焦点停留在配置了tabStop的容器内部时，可以走焦到容器内部的下一个可获焦组件，如果焦点停留在配置了tabStop的容器外部时，可以走焦到容器外的下一个可获焦组件。 2.当焦点停留在tabStop上时，按Enter键可以走焦到内部第一个可获焦组件，按ESC能够将焦点退回到不超过当前层级页面根容器的上一个配置了tabStop的组件，按空格键可以响应该容器的onClick事件。 3.不建议根容器配置tabStop。如果根容器配置了tabStop，通过clearFocus将焦点清理到根容器，再按Enter键会重新走回内部上一次获焦组件，通过ESC键将焦点清理到根容器，再按Enter键会走焦到内部第一个可获焦组件。

参数名

类型

必填

说明

isTabStop

boolean

是

设置当前容器组件是否为走焦可停留容器。

说明：

1.配置tabStop需要保障是容器组件且有可获焦的孩子组件，默认容器组件不能直接获焦。

2.通过requestFocus请求焦点，如果是容器组件且配置tabStop，焦点能够停留在容器组件，如果未配置tabStop，即使整条焦点链上有配置了tabStop的组件，该组件依然能获取到焦点。

3.配置tabStop的容器不允许嵌套超过2层。

tabStop走焦规则：

1.通过tab键和方向键走焦，焦点会停留在配置了tabStop的组件上，如果焦点停留在配置了tabStop的容器内部时，可以走焦到容器内部的下一个可获焦组件，如果焦点停留在配置了tabStop的容器外部时，可以走焦到容器外的下一个可获焦组件。

2.当焦点停留在tabStop上时，按Enter键可以走焦到内部第一个可获焦组件，按ESC能够将焦点退回到不超过当前层级页面根容器的上一个配置了tabStop的组件，按空格键可以响应该容器的onClick事件。

3.不建议根容器配置tabStop。如果根容器配置了tabStop，通过clearFocus将焦点清理到根容器，再按Enter键会重新走回内部上一次获焦组件，通过ESC键将焦点清理到根容器，再按Enter键会走焦到内部第一个可获焦组件。

描述走焦的时候的按键以及获焦组件

当前焦点如果停留在button2时，按下tab键将会走焦到Column3上，再按下tab键会循环走焦到button1上。

示例

示例1（设置组件获焦和走焦的效果）

该示例通过配置defaultFocus可以使绑定的组件成为页面创建后首次获焦的焦点，配置groupDefaultFocus可以使绑定的组件成为tabIndex容器创建后首次获焦的焦点，配置focusOnTouch可以使绑定的组件点击后立即获焦。

// focusTest.ets
@Entry
@Component
struct FocusableExample {
  @State inputValue: string = ''

  build() {
    Scroll() {
      Row({ space: 20 }) {
        Column({ space: 20 }) {
          Column({ space: 5 }) {
            Button('Group1')
              .width(165)
              .height(40)
              .fontColor(Color.White)
              .focusOnTouch(true)           // 该Button组件点击后可获焦
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
                .focusOnTouch(true)           // 该Button组件点击后可获焦
            }
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
            }
          }.borderWidth(2).borderColor(Color.Red).borderStyle(BorderStyle.Dashed)
          .tabIndex(1)                      // 该Column组件为按TAB键走焦的第一个获焦的组件
          Column({ space: 5 }) {
            Button('Group2')
              .width(165)
              .height(40)
              .fontColor(Color.White)
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
                .groupDefaultFocus(true)      // 该Button组件上级Column组件获焦时获焦
            }
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
            }
          }.borderWidth(2).borderColor(Color.Green).borderStyle(BorderStyle.Dashed)
          .tabIndex(2)                      // 该Column组件为按TAB键走焦的第二个获焦的组件
        }
        Column({ space: 5 }) {
          TextInput({placeholder: 'input', text: this.inputValue})
            .onChange((value: string) => {
              this.inputValue = value
            })
            .width(156)
            .defaultFocus(true)             // 该TextInput组件为页面的初始默认焦点
          Button('Group3')
            .width(165)
            .height(40)
            .fontColor(Color.White)
          Row({ space: 5 }) {
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
          }
          Button()
            .width(165)
            .height(40)
            .fontColor(Color.White)
          Row({ space: 5 }) {
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
          }
          Button()
            .width(165)
            .height(40)
            .fontColor(Color.White)
          Row({ space: 5 }) {
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
          }
        }.borderWidth(2).borderColor(Color.Orange).borderStyle(BorderStyle.Dashed)
        .tabIndex(3)                      // 该Column组件为按TAB键走焦的第三个获焦的组件
      }.alignItems(VerticalAlign.Top)
    }
  }
}

示意图：

首次进入，焦点默认在defaultFocus绑定的TextInput组件上：

首次按TAB键，焦点切换到tabIndex(1)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上：

第二次按TAB键，焦点切换到tabIndex(2)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上：

第三次按TAB键，焦点切换到tabIndex(3)的容器上，且自动走到其内部的groupDefaultFocus绑定的组件上：

点击绑定了focusOnTouch的组件，组件自身获焦，焦点框被清除，再按下Tab键显示焦点框：

示例2（设置指定组件获焦）

该示例通过配置focusControl.requestFocus使指定组件获取焦点。

说明

直接使用focusControl可能导致实例不明确的问题，建议使用getUIContext获取UIContext实例，并使用getFocusController获取绑定实例的focusControl。

// requestFocus.ets
@Entry
@Component
struct RequestFocusExample {
  @State idList: string[] = ['A', 'B', 'C', 'D', 'E', 'F', 'LastPageId']
  @State selectId: string = 'LastPageId'

  build() {
    Column({ space:20 }){
      Row({space: 5}) {
        Button("id: " + this.idList[0] + " focusable(false)")
          .width(200).height(70).fontColor(Color.White)
          .id(this.idList[0])
          .focusable(false)
        Button("id: " + this.idList[1])
          .width(200).height(70).fontColor(Color.White)
          .id(this.idList[1])
      }
      Row({space: 5}) {
        Button("id: " + this.idList[2])
          .width(200).height(70).fontColor(Color.White)
          .id(this.idList[2])
        Button("id: " + this.idList[3])
          .width(200).height(70).fontColor(Color.White)
          .id(this.idList[3])
      }
      Row({space: 5}) {
        Button("id: " + this.idList[4])
          .width(200).height(70).fontColor(Color.White)
          .id(this.idList[4])
        Button("id: " + this.idList[5])
          .width(200).height(70).fontColor(Color.White)
          .id(this.idList[5])
      }
      Row({space: 5}) {
        Select([{value: this.idList[0]},
                {value: this.idList[1]},
                {value: this.idList[2]},
                {value: this.idList[3]},
                {value: this.idList[4]},
                {value: this.idList[5]},
                {value: this.idList[6]}])
          .value(this.selectId)
          .onSelect((index: number) => {
            this.selectId = this.idList[index]
          })
        Button("RequestFocus")
          .width(200).height(70).fontColor(Color.White)
          .onClick(() => {
            // 建议使用this.getUIContext().getFocusController().requestFocus()
            let res = focusControl.requestFocus(this.selectId)      // 使选中的this.selectId的组件获焦
            if (res) {
              this.getUIContext().getPromptAction().showToast({message: 'Request success'})
            } else {
              this.getUIContext().getPromptAction().showToast({message: 'Request failed'})
            }
          })
      }
    }.width('100%').margin({ top:20 })
  }
}

示意图：

按下TAB键，激活焦点态显示。

申请不存在的组件获焦：

申请不可获焦的组件获焦：

申请存在且可获焦的组件获焦：

示例3（设置焦点框样式）

该示例通过配置focusBox修改组件的焦点框样式。

import { ColorMetrics, LengthMetrics } from '@kit.ArkUI'

@Entry
@Component
struct RequestFocusExample {
  build() {
    Column({ space: 30 }) {
      Button("small black focus box")
        .focusBox({
          margin: new LengthMetrics(0),
          strokeColor: ColorMetrics.rgba(0, 0, 0),
        })
      Button("large red focus box")
        .focusBox({
          margin: LengthMetrics.px(20),
          strokeColor: ColorMetrics.rgba(255, 0, 0),
          strokeWidth: LengthMetrics.px(10)
        })
    }
    .alignItems(HorizontalAlign.Center)
    .width('100%')
  }
}

示例4（设置焦点组走焦）

该示例通过配置focusScopePriority可以使绑定的组件成为所属容器首次获焦时的焦点，配置focusScopeId可以使绑定的容器组件组件成为焦点组。

// focusTest.ets
@Entry
@Component
struct FocusableExample {
  @State inputValue: string = ''

  build() {
    Scroll() {
      Row({ space: 20 }) {
        Column({ space: 20 }) {  // 标记为Column1
          Column({ space: 5 }) {
            Button('Group1')
              .width(165)
              .height(40)
              .fontColor(Color.White)
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
            }
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
            }
          }.borderWidth(2).borderColor(Color.Red).borderStyle(BorderStyle.Dashed)
          Column({ space: 5 }) {
            Button('Group2')
              .width(165)
              .height(40)
              .fontColor(Color.White)
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
                .focusScopePriority('ColumnScope1', FocusPriority.PRIOR)  // Column1首次获焦时获焦
            }
            Row({ space: 5 }) {
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
              Button()
                .width(80)
                .height(40)
                .fontColor(Color.White)
            }
          }.borderWidth(2).borderColor(Color.Green).borderStyle(BorderStyle.Dashed)
        }
        .focusScopeId('ColumnScope1')
        Column({ space: 5 }) {  // 标记为Column2
          TextInput({placeholder: 'input', text: this.inputValue})
            .onChange((value: string) => {
              this.inputValue = value
            })
            .width(156)
          Button('Group3')
            .width(165)
            .height(40)
            .fontColor(Color.White)
          Row({ space: 5 }) {
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
          }
          Button()
            .width(165)
            .height(40)
            .fontColor(Color.White)
            .focusScopePriority('ColumnScope2', FocusPriority.PREVIOUS)  // Column2获焦时获焦
          Row({ space: 5 }) {
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
          }
          Button()
            .width(165)
            .height(40)
            .fontColor(Color.White)
          Row({ space: 5 }) {
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
            Button()
              .width(80)
              .height(40)
              .fontColor(Color.White)
          }
        }.borderWidth(2).borderColor(Color.Orange).borderStyle(BorderStyle.Dashed)
        .focusScopeId('ColumnScope2', true)  // Column2为焦点组
      }.alignItems(VerticalAlign.Top)
    }
  }
}

示例5（设置tab走焦停留）

该示例通过配置tabstop实现使用tab走焦停留在组件上。

import { ColorMetrics, LengthMetrics } from '@kit.ArkUI'

@Entry
@Component
struct TabStop {
  build() {
    Column({ space: 20 }) {
      Column({ space: 20 }) {
        Column({ space: 20 }) {
          Row({ space: 5 }) {
            Button("button 1")
              .width(200).height(70).fontColor(Color.White)
              .focusBox({
                margin: LengthMetrics.px(20),
                strokeColor: ColorMetrics.rgba(23, 169, 141),
                strokeWidth: LengthMetrics.px(10)
              })
          }
          Row({ space: 5 }) {
            Button("button 2")
              .width(200).height(70).fontColor(Color.White)
              .focusBox({
                margin: LengthMetrics.px(20),
                strokeColor: ColorMetrics.rgba(23, 169, 141),
                strokeWidth: LengthMetrics.px(10)
              })
          }
        }.width('80%').margin({ top: 30 }).borderColor(Color.Black)
      }.width('95%').margin({ top: 60 }).borderColor(Color.Black)
      Column({ space: 20 }) {
        Column({ space: 20 }) {
          Row({ space: 5 }) {
            Button("button 3")
              .width(200)
              .height('70%')
              .fontColor(Color.White)
              .focusBox({
                margin: LengthMetrics.px(20),
                strokeColor: ColorMetrics.rgba(23, 169, 141),
                strokeWidth: LengthMetrics.px(10)
              })
              .margin({ top: 15 })
          }
        }
        .width('80%')
        .height('120')
        .borderColor(Color.Black)
        .margin({ top: 10 })
        .tabStop(true)
        .focusBox({
          margin: LengthMetrics.px(20),
          strokeColor: ColorMetrics.rgba(23, 169, 141),
          strokeWidth: LengthMetrics.px(10)
        })
        .borderWidth(1)
      }.width('95%').margin({ top: 50 }).borderColor(Color.Black)
    }
  }
}

示意图：

连续按下两次TAB键时，焦点转移到button2上。

接着按下TAB键，焦点转移到配置了tabStop的组件。

再按下Enter键，焦点转移至内部button3上。

再按下ESC键，焦点转移到配置了tabStop的组件上。

再按下TAB键，焦点循环走焦到button1上。

HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

携手共建场景化解决方案共享鸿蒙新世界

共创新价值，从“使用鸿蒙”走向“共建鸿蒙”，从“技术受益者”成为“生态贡献者”，携手共建共享鸿蒙新世界。技术介绍资料，包括技术名称、技术能力介绍、技术应用场景、技术能力价值/亮点、使用案例及联系方式，华为。这些成果不仅是技术的突破，更是鸿蒙生态“共建、共享、共赢”理念的最佳实践。鸿蒙生态秉承着持续开放、协同共建的发展理念，为积极参与。

HarmonyOS开发者社区

CodeGenie AI辅助开发意图，让小艺“看见”你的鸿蒙应用

是功能更强大和灵活的一个装饰器，绑定UIAbility/UIExtensionAbility组件，允许你配置Ability的执行模式（前台或后台），你可以在对应的模式回调方法中实现复杂的意图处理逻辑，比如跳转到不同的页面或执行一系列操作。MusicListPage类的头部后，在装饰器的代码块内点击“右键” => “Code Genie” => “Add Intent Plugin”，即可在IDE的

HarmonyOS开发者社区

鸿蒙美食元服务快速开发指南：低门槛入局，抢占赛道红利！

本模板已集成预加载、华为账号、地图、华为支付、通话等服务，只需做少量配置和定制即可快速实现页面的快速加载、华为账号的登录、商家位置定位导航、购买餐饮和联系商家等功能。：本模板为餐饮茶饮类元服务提供了常用功能的开发样例，模板主要分首页、点单、我的订单和我的四大模块。本模板为餐厅排队元服务提供了常用功能的开发样例，模板主要分首页和我的两大模块：首页：主要提供订座和排号的入口。提供了浏览门店、立即订座