HarmonyOS NEXT实战开发：Tabs组件

通过页签进行内容视图切换的容器组件，每个页签对应一个内容视图。

说明

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

该组件从API Version 11开始默认支持安全区避让特性(默认值为：expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM]))，开发者可以重写该属性覆盖默认行为，API Version 11之前的版本需配合expandSafeArea属性实现安全区避让。

子组件

不支持自定义组件作为子组件， 仅可包含子组件TabContent， 以及渲染控制类型if/else和ForEach, 并且if/else和ForEach下也仅支持TabContent, 不支持自定义组件。

说明

Tabs子组件的visibility属性设置为None，或者visibility属性设置为Hidden时，对应子组件不显示，但依然会在视窗内占位。

接口

Tabs(value?: {barPosition?: BarPosition, index?: number, controller?: TabsController})

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

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

参数：

参数名	参数类型	必填	参数描述
barPosition	BarPosition	否	设置Tabs的页签位置。 默认值：BarPosition.Start
index	number	否	设置当前显示页签的索引。 默认值：0 说明： 设置为小于0的值时按默认值显示。 可选值为[0, TabContent子节点数量-1]。 直接修改index跳页时，切换动效不生效。 使用TabController的changeIndex时，默认生效切换动效，可以设置animationDuration为0关闭动画。 从API version 10开始，该参数支持$$双向绑定变量。
controller	TabsController	否	设置Tabs控制器。

BarPosition枚举说明

Tabs页签位置枚举。

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

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

名称	描述
Start	vertical属性方法设置为true时，页签位于容器左侧；vertical属性方法设置为false时，页签位于容器顶部。
End	vertical属性方法设置为true时，页签位于容器右侧；vertical属性方法设置为false时，页签位于容器底部。

属性

除支持通用属性外，还支持以下属性：

vertical

vertical(value: boolean)

设置是否为纵向Tab。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	是否为纵向Tab。 默认值：false，横向Tabs，为true时纵向Tabs。 当横向Tabs设置height为auto时，Tabs组件高度自适应子组件高度，即为tabBar高度+divider线宽+TabContent高度+上下padding值+上下border宽度。 当纵向Tabs设置width为auto时，Tabs组件宽度自适应子组件宽度，即为tabBar宽度+divider线宽+TabContent宽度+左右padding值+左右border宽度。 尽量保持每一个页面中的子组件尺寸大小一致，避免滑动页面时出现页面切换动画跳动现象。

scrollable

scrollable(value: boolean)

设置是否可以通过滑动页面进行页面切换。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	是否可以通过滑动页面进行页面切换。 默认值：true，可以通过滑动页面进行页面切换。为false时不可滑动切换页面。

barMode

barMode(value: BarMode, options?: ScrollableBarModeOptions)

设置TabBar布局模式。

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

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

参数：

参数名	类型	必填	说明
value	BarMode	是	布局模式。 默认值：BarMode.Fixed
options10+	ScrollableBarModeOptions	否	Scrollable模式下的TabBar的布局样式。 说明： 仅Scrollable模式下有效

barWidth

barWidth(value: Length)

设置TabBar的宽度值。设置为小于0或大于Tabs宽度值时，按默认值显示。

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

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

参数：

参数名	类型	必填	说明
value	Length8+	是	TabBar的宽度值。 默认值： 未设置SubTabBarStyle和BottomTabBarStyle的TabBar且vertical属性为false时，默认值为Tabs的宽度。 未设置SubTabBarStyle和BottomTabBarStyle的TabBar且vertical属性为true时，默认值为56vp。 设置SubTabbarStyle样式且vertical属性为false时，默认值为Tabs的宽度。 设置SubTabbarStyle样式且vertical属性为true时，默认值为56vp。 设置BottomTabbarStyle样式且vertical属性为true时，默认值为96vp。 设置BottomTabbarStyle样式且vertical属性为false时，默认值为Tabs的宽度。

barHeight

barHeight(value: Length)

设置TabBar的高度值。设置为小于0或大于Tabs高度值时，按默认值显示。

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

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

参数：

参数名	类型	必填	说明
value	Length8+	是	TabBar的高度值。 默认值： 未设置带样式的TabBar且vertical属性为false时，默认值为56vp。 未设置带样式的TabBar且vertical属性为true时，默认值为Tabs的高度。 设置SubTabbarStyle样式且vertical属性为false时，默认值为56vp。 设置SubTabbarStyle样式且vertical属性为true时，默认值为Tabs的高度。 设置BottomTabbarStyle样式且vertical属性为true时，默认值为Tabs的高度。 设置BottomTabbarStyle样式且vertical属性为false时，默认值为56vp, 从API Version 12开始，默认值变更为52vp。

animationDuration

animationDuration(value: number)

设置点击TabBar页签和调用TabsController的changeIndex接口切换TabContent的动画时长。该参数不支持百分比设置。

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

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

参数：

参数名	类型	必填	说明
value	number	是	点击TabBar页签和调用TabsController的changeIndex接口切换TabContent的动画时长。 默认值： API version 10及以前，不设置该属性或设置为null时，默认值为0ms，即点击TabBar页签和调用TabsController的changeIndex接口切换TabContent无动画。设置为小于0或undefined时，默认值为300ms。 API version 11及以后，不设置该属性或设置为异常值，且设置TabBar为BottomTabBarStyle样式时，默认值为0ms。设置TabBar为其他样式时，默认值为300ms。

animationMode12+

animationMode(mode: Optional<AnimationMode>)

设置点击TabBar页签时切换TabContent的动画形式。

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

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

参数：

参数名	类型	必填	说明
mode	Optional<AnimationMode>	是	点击TabBar页签时切换TabContent的动画形式。 默认值： 默认值是AnimationMode::CONTENT_FIRST，表示在点击TabBar切换TabContent时，先加载目标页内容，再开始切换动画。

divider10+

divider(value: DividerStyle | null)

设置区分TabBar和TabContent的分割线样式。

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

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

参数：

参数名	类型	必填	说明
value	DividerStyle | null	是	分割线样式，默认不显示分割线。 DividerStyle: 分割线的样式； null: 不显示分割线。

fadingEdge10+

fadingEdge(value: boolean)

设置页签超过容器宽度时是否渐隐消失。建议配合barBackgroundColor属性一起使用，如果barBackgroundColor属性没有定义，会默认显示页签末端为白色的渐隐效果。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	页签超过容器宽度时是否渐隐消失。 默认值：true

barOverlap10+

barOverlap(value: boolean)

设置TabBar是否背后变模糊并叠加在TabContent之上。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	TabBar是否背后变模糊并叠加在TabContent之上。 默认值：false

barBackgroundColor10+

barBackgroundColor(value: ResourceColor)

设置TabBar的背景颜色。

元服务API： 从