文档管理中心

SegmentButton

Phone12+PC/2in113+Tablet12+TV19+

分段按钮组件包含页签类分段按钮和胶囊类分段按钮。页签类分段按钮适用于页面或内容区域的切换场景;胶囊类分段按钮适用于单选或多选的选择场景,包含胶囊类单选分段按钮和胶囊类多选分段按钮。该组件支持自定义文本颜色、字体大小、字体粗细、背景色、图片尺寸、内边距、背景模糊材质等外观属性,支持仅文本、仅图标和图标+文本三种按钮样式,并提供无障碍朗读、布局方向镜像、自定义圆角、属性动画等能力,适用于需要快速构建符合设计规范的分段选择界面的场景。

说明
  • 该组件从API version 11开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

  • 本模块接口仅可在Stage模型下使用。

导入模块

收起
自动换行
深色代码主题
复制
  1. import { SegmentButton, SegmentButtonOptions, SegmentButtonItemOptionsArray } from '@kit.ArkUI';

子组件

属性

不支持通用属性

事件

不支持通用事件

SegmentButton

Phone12+PC/2in113+Tablet12+TV19+

SegmentButton({ options: SegmentButtonOptions, selectedIndexes: number[], onItemClicked?: Callback<number>, maxFontScale: number | Resource, enableStateAnimation: boolean })

装饰器类型:@Component

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

说明
  • 分段按钮不支持通用属性。分段按钮使用当前区域可使用的最大宽度作为组件宽度,并且根据按钮个数平均分配每个按钮宽度;分段按钮高度根据按钮内容(文本及图片)自动适应,其最小高度为28vp。

  • @Prop装饰的属性为可选参数,仅当与@Require装饰器联合使用时,才必须在构造时传入对应参数。

展开
名称 类型 必填 装饰器类型 说明
options SegmentButtonOptions @ObjectLink

分段按钮的配置选项,用于设置按钮的类型(页签类或胶囊类)、外观样式(颜色、字体、尺寸等)、按钮内容和选中状态等属性。

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

selectedIndexes number[] @Link

分段按钮的选中项编号,第一项的编号为0,之后顺序增加。

说明:

selectedIndexes使用@Link装饰器:父子双向同步,仅支持有效的按钮编号(第一个按钮编号为0,之后按顺序累加,最大编号为按钮数量减1),传入无效编号时该编号不生效。如没有选中项可传入空数组[]。

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

onItemClicked13+ Callback<number> -

当分段按钮选项被点击时,触发的回调函数接收被点击的选项下标作为参数。若不传入此参数,则点击时不触发回调。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

maxFontScale14+ number | Resource @Prop

分段按钮选项文字的最大字体放大倍数,用于限制字体缩放上限。当需要控制字体放大倍数以适应特定UI布局或避免文字过大时传入此参数。

取值范围:[1, 2]

当设置的值小于1时,按值为1处理,设置的值大于2时,按值为2处理。

默认值:1

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

enableStateAnimation24+ boolean @Prop

设置当通过变量修改selectedIndexes值时,是否开启分段按钮的属性动画。

true表示开启分段按钮的属性动画;false表示不开启分段按钮的属性动画。

默认值:false

元服务API: 从API version 24开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

SegmentButtonOptions

Phone12+PC/2in113+Tablet12+TV19+
说明

不支持设置字体类型。

分段按钮选项类用于提供初始数据和自定义属性。

装饰器类型: @Observed

属性

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
type "tab" | "capsule"

分段按钮组件的类型。

说明:

"tab":页签类分段按钮,适用于页面或内容区域的切换场景。

"capsule":胶囊类分段按钮,适用于单选或多选的选择场景。

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

multiply boolean

分段按钮组件是否可以多选。

true:可多选;false:不可多选。

页签类分段按钮(type为"tab")时,multiply强制为false,设置true不生效。

默认值: false

值为undefined时,按默认值处理。

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

buttons SegmentButtonItemOptionsArray

分段按钮组件的按钮信息,包括图标和文本信息。

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

fontColor ResourceColor

分段按钮组件的按钮未选中态的文本颜色。

值为undefined时,颜色为$r('sys.color.ohos_id_color_text_secondary')。

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

selectedFontColor ResourceColor

分段按钮组件的按钮选中态的文本颜色。

值为undefined时,type为"tab"时,颜色为$r('sys.color.ohos_id_color_text_primary')。

type为"capsule"时,颜色为$r('sys.color.ohos_id_color_foreground_contrary')。

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

fontSize DimensionNoPercentage

分段按钮组件的按钮未选中态的字体大小,不支持百分比设置。

单位:fp

值为undefined时,字体大小为$r('sys.float.ohos_id_text_size_body2')。

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

selectedFontSize DimensionNoPercentage

分段按钮组件的按钮选中态的字体大小,不支持百分比设置。

单位:fp

值为undefined时,字体大小为$r('sys.float.ohos_id_text_size_body2')。

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

fontWeight FontWeight

分段按钮组件的按钮未选中态的字体粗细。

值为undefined时,字体粗细为FontWeight.Regular。

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

selectedFontWeight FontWeight

分段按钮组件的按钮选中态的字体粗细。

值为undefined时,字体粗细为FontWeight.Medium。

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

backgroundColor ResourceColor

分段按钮组件的背景板颜色。

值为undefined时,背景板颜色为$r('sys.color.ohos_id_color_button_normal')。

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

selectedBackgroundColor ResourceColor

分段按钮组件的按钮选中态背景板颜色。

值为undefined时,type为"tab"时,背景板颜色为$r('sys.color.segment_button_checked_foreground_color')。

type为"capsule"时,背景板颜色为$r('sys.color.ohos_id_color_emphasize')。

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

imageSize SizeOptions

分段按钮组件的图片尺寸。

值为undefined时,图片尺寸为{ width: 24, height: 24 }。

单位:vp

说明:

imageSize属性对仅图标按钮和图标+文本按钮生效,对纯文本按钮无效果。

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

buttonPadding Padding | Dimension

分段按钮组件的按钮内边距。

值为undefined时,仅图标按钮和仅文字按钮内边距:{ top: 4, right: 8, bottom: 4, left: 8 }

图标+文本按钮内边距:{ top: 6, right: 8, bottom: 6, left: 8 }

单位:vp

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

textPadding Padding | Dimension

分段按钮组件的文本内边距。

值为undefined时,文本内边距为0。

单位:vp

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

localizedButtonPadding12+ LocalizedPadding

分段按钮组件的按钮内边距,支持随布局方向(LTR/RTL)自适应。

默认值:

仅图标按钮和仅文字按钮默认值:{ top: LengthMetrics.vp(4), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(4), start: LengthMetrics.vp(8) }

图标+文本按钮默认值:{ top: LengthMetrics.vp(6), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(6), start: LengthMetrics.vp(8) }

值为undefined时,按默认值处理。

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

localizedTextPadding12+ LocalizedPadding

文本内边距,支持随布局方向(LTR/RTL)自适应。

默认值:0

单位:vp

值为undefined时,按默认值处理。

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

direction12+ Direction

分段按钮组件的布局方向。

默认值:Direction.Auto

值为undefined时,按默认值处理。

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

backgroundBlurStyle BlurStyle

分段按钮组件的背景模糊材质。

默认值:BlurStyle.NONE

值为undefined时,按默认值处理。

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

borderRadiusMode20+ BorderRadiusMode

边框圆角模式,用于控制圆角计算方式。

默认值:BorderRadiusMode.DEFAULT

值为undefined时,按默认值处理。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

backgroundBorderRadius20+ LengthMetrics

分段按钮整体容器的边框圆角半径。

说明:

此属性仅在borderRadiusMode为BorderRadiusMode.CUSTOM时生效。

对于胶囊类多选分段按钮(type为"capsule"且multiply为true),此属性不生效,需要用itemBorderRadius配置圆角。

圆角大小受组件尺寸限制,最大值为组件宽或高的一半,不支持百分比设置。超出最大值时自动修正为最大值,使用百分比时按默认值处理。

默认值:$r('sys.float.segmentbutton_container_shape')

值为undefined时,按默认值处理。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

itemBorderRadius20+ LengthMetrics

分段按钮中按钮项的边框圆角半径。

说明:

此属性仅在borderRadiusMode为BorderRadiusMode.CUSTOM时生效。

对于胶囊类多选分段按钮(type为"capsule"且multiply为true),只能控制两端的选项圆角。

圆角大小受组件尺寸限制,最大值为组件宽或高的一半,不支持百分比设置。超出最大值时自动修正为最大值,使用百分比时按默认值处理。

默认值:$r('sys.float.segmentbutton_selected_background_shape')

值为undefined时,按默认值处理。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

backgroundSystemMaterial uiMaterial.Material

分段按钮组件的背景板的系统材质。需要将组件放置在Navigation或NavDestination的标题栏子树,或横向Tabs的底部TabBar子树中,材质效果才会生效。不同系统材质具有不同的属性,产生不同的效果。传入材质后,SegmentButton的动效发生改变。

对于胶囊类多选分段按钮(即type为"capsule"且multiply为true),该属性不生效。

默认值:无材质效果。

起始版本: 26.0.0

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

说明

从API版本26.0.0开始,除胶囊类多选按钮(即type为"capsule"且multiply为true)外,backgroundSystemMaterial设置自动反色的系统材质时,fontColor和selectedFontColor使用支持反色的特殊系统资源,颜色自动适配到材质背景色的反色。

constructor

Phone12+PC/2in113+Tablet12+TV19+

constructor(options: TabSegmentButtonOptions | CapsuleSegmentButtonOptions)

构造函数。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数

展开
参数名 类型 必填 说明
options TabSegmentButtonOptions | CapsuleSegmentButtonOptions 页签类或者胶囊类分段按钮信息。

tab

Phone12+PC/2in113+Tablet12+TV19+

static tab(options: TabSegmentButtonConstructionOptions): SegmentButtonOptions

创建SegmentButtonOptions类,用于定义页签。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数

展开
参数名 类型 必填 说明
options TabSegmentButtonConstructionOptions 页签类分段按钮信息。

返回值:

展开
类型 说明
SegmentButtonOptions 分段按钮选项,用于定义页签类分段按钮。

capsule

Phone12+PC/2in113+Tablet12+TV19+

static capsule(options: CapsuleSegmentButtonConstructionOptions): SegmentButtonOptions

创建胶囊类的SegmentButtonOptions,用于定义胶囊类分段按钮。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数

展开
参数名 类型 必填 说明
options CapsuleSegmentButtonConstructionOptions 胶囊类分段按钮信息。

返回值:

展开
类型 说明
SegmentButtonOptions 分段按钮选项,用于定义胶囊类分段按钮。

DimensionNoPercentage

Phone12+PC/2in113+Tablet12+TV19+

type DimensionNoPercentage = PX | VP | FP | LPX | Resource

不支持百分比类型的长度联合类型。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
类型 说明
PX 长度类型,用于描述以px为单位的长度。
VP 长度类型,用于描述以vp为单位的长度。
FP 长度类型,用于描述以fp为单位的长度。
LPX 长度类型,用于描述以lpx为单位的长度。
Resource 资源引用类型,用于设置组件属性的值。

CommonSegmentButtonOptions

Phone12+PC/2in113+Tablet12+TV19+

定义分段按钮组件的可自定义的属性。

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
fontColor ResourceColor

按钮未选中态的文本颜色。

默认值:$r('sys.color.ohos_id_color_text_secondary')

值为undefined时,按默认值处理。

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

selectedFontColor ResourceColor

按钮选中态的文本颜色。

默认值:

type为"tab"时,默认值为$r('sys.color.ohos_id_color_text_primary')。

type为"capsule"时,默认值为$r('sys.color.ohos_id_color_foreground_contrary')。

值为undefined时,按默认值处理。

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

fontSize DimensionNoPercentage

按钮未选中态的字体大小(不支持百分比设置)。

默认值:$r('sys.float.ohos_id_text_size_body2')

单位:fp

值为undefined时,按默认值处理。

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

selectedFontSize DimensionNoPercentage

按钮选中态的字体大小(不支持百分比设置)。

默认值:$r('sys.float.ohos_id_text_size_body2')

单位:fp

值为undefined时,按默认值处理。

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

fontWeight FontWeight

按钮未选中态的字体粗细。

默认值:FontWeight.Regular

值为undefined时,按默认值处理。

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

selectedFontWeight FontWeight

按钮选中态的字体粗细。

默认值:FontWeight.Medium

值为undefined时,按默认值处理。

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

backgroundColor ResourceColor

背景板颜色。

默认值:$r('sys.color.ohos_id_color_button_normal')

值为undefined时,按默认值处理。

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

selectedBackgroundColor ResourceColor

按钮选中态的背景板颜色。

默认值:

type为"tab"时,默认值为$r('sys.color.segment_button_checked_foreground_color')。

type为"capsule"时,默认值为$r('sys.color.ohos_id_color_emphasize')。

值为undefined时,按默认值处理。

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

imageSize SizeOptions

图片尺寸。

默认值:{ width: 24, height: 24 }

单位:vp

值为undefined时,按默认值处理。

说明:

imageSize属性仅对图标按钮和图标+文本按钮生效,对纯文本按钮无效果。

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

buttonPadding Padding | Dimension

按钮内边距。

默认值:

仅图标按钮和仅文字按钮默认值:{ top: 4, right: 8, bottom: 4, left: 8 }

图标+文本按钮默认值:{ top: 6, right: 8, bottom: 6, left: 8 }

单位:vp

值为undefined时,按默认值处理。

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

textPadding Padding | Dimension

文本内边距。

默认值:0

单位:vp

值为undefined时,按默认值处理。

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

localizedButtonPadding12+ LocalizedPadding

按钮内边距,支持随布局方向(LTR/RTL)自适应。

默认值:

仅图标按钮和仅文字按钮默认值:{ top: LengthMetrics.vp(4), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(4), start: LengthMetrics.vp(8) }

图标+文本按钮默认值:{ top: LengthMetrics.vp(6), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(6), start: LengthMetrics.vp(8) }

值为undefined时,按默认值处理。

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

localizedTextPadding12+ LocalizedPadding

文本内边距,支持随布局方向(LTR/RTL)自适应。

默认值:0

单位:vp

值为undefined时,按默认值处理。

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

direction12+ Direction

布局方向。

默认值:Direction.Auto

值为undefined时,按默认值处理。

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

backgroundBlurStyle BlurStyle

背景模糊材质。

默认值:BlurStyle.NONE

值为undefined时,按默认值处理。

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

borderRadiusMode20+ BorderRadiusMode

边框圆角模式,用于控制圆角计算方式。

默认值:BorderRadiusMode.DEFAULT

值为undefined时,按默认值处理。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

backgroundBorderRadius20+ LengthMetrics

分段按钮整体容器的边框圆角半径。

说明:

此属性仅在borderRadiusMode为BorderRadiusMode.CUSTOM时生效。

对于胶囊类多选分段按钮(type为"capsule"且multiply为true),此属性不生效,需要用itemBorderRadius配置圆角。

圆角大小受组件尺寸限制,最大值为组件宽或高的一半,不支持百分比设置。超出最大值时自动修正为最大值,使用百分比时按默认值处理。

默认值:$r('sys.float.segmentbutton_container_shape')

值为undefined时,按默认值处理。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

itemBorderRadius20+ LengthMetrics

分段按钮中按钮项的边框圆角半径。

说明:

此属性仅在borderRadiusMode为BorderRadiusMode.CUSTOM时生效。

对于胶囊类多选分段按钮(type为"capsule"且multiply为true),只能控制两端的选项圆角。

圆角大小受组件尺寸限制,最大值为组件宽或高的一半,不支持百分比设置。超出最大值时自动修正为最大值,使用百分比时按默认值处理。

默认值:$r('sys.float.segmentbutton_selected_background_shape')

值为undefined时,按默认值处理。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

backgroundSystemMaterial uiMaterial.Material

分段按钮组件的背景板的系统材质。需要将组件放置在Navigation或NavDestination的标题栏子树,或横向Tabs的底部TabBar子树中,材质效果才会生效。不同系统材质具有不同的属性,产生不同的效果。传入材质后,SegmentButton的动效发生改变。

对于胶囊类多选分段按钮(即type为"capsule"且multiply为true),该属性不生效。

默认值:无材质效果。

从API版本26.0.0开始,除胶囊类多选分段按钮(即type为"capsule"且multiply为true)外,backgroundSystemMaterial设置自动反色的系统材质时,fontColor和selectedFontColor使用支持反色的特殊系统资源,颜色自动适配到材质背景色的反色。

起始版本: 26.0.0

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

BorderRadiusMode20+

Phone20+PC/2in120+Tablet20+TV20+

边框圆角模式枚举,用于控制分段按钮的圆角计算方式。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 说明
DEFAULT 0 默认模式,框架自动计算边框圆角。
CUSTOM 1 自定义模式,开发者设置边框圆角。

TabSegmentButtonConstructionOptions

Phone12+PC/2in113+Tablet12+TV19+

构建页签类的SegmentButtonOptions对象。

继承CommonSegmentButtonOptions

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
buttons ItemRestriction<SegmentButtonTextItem> 按钮信息。

CapsuleSegmentButtonConstructionOptions

Phone12+PC/2in113+Tablet12+TV19+

用于构建胶囊类的SegmentButtonOptions对象。

继承CommonSegmentButtonOptions

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
buttons SegmentButtonItemTuple 按钮信息。
multiply boolean

是否可以多选。

默认值:false

值为undefined时,按默认值处理。

true表示可以多选,false表示不可以多选。

ItemRestriction

Phone12+PC/2in113+Tablet12+TV19+

type ItemRestriction<T> = [T, T, T?, T?, T?]

保存按钮信息的元组类型。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
类型 说明
[T, T, T?, T?, T?] 表示包含2~5个相同类型元素的元组。
说明

分段按钮组件仅支持2到5个按钮。

SegmentButtonItemTuple

Phone12+PC/2in113+Tablet12+TV19+

type SegmentButtonItemTuple = ItemRestriction<SegmentButtonTextItem> | ItemRestriction<SegmentButtonIconItem> | ItemRestriction<SegmentButtonIconTextItem>

用于保存按钮信息的元组的联合类型。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
类型 说明
ItemRestriction<SegmentButtonTextItem> 仅文本按钮信息的元组。
ItemRestriction<SegmentButtonIconItem> 仅图标按钮信息的元组。
ItemRestriction<SegmentButtonIconTextItem> 图标+文本按钮信息的元组。

SegmentButtonItemArray

Phone12+PC/2in113+Tablet12+TV19+

type SegmentButtonItemArray = Array<SegmentButtonTextItem> | Array<SegmentButtonIconItem> | Array<SegmentButtonIconTextItem>

用于保存按钮信息的数组的联合类型。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
类型 说明
Array<SegmentButtonTextItem> 仅文本按钮信息的数组。
Array<SegmentButtonIconItem> 仅图标按钮信息的数组。
Array<SegmentButtonIconTextItem> 图标+文本按钮信息的数组。

SegmentButtonItemOptionsArray

Phone12+PC/2in113+Tablet12+TV19+

用于保存按钮信息的数组。

装饰器类型: @Observed

说明

SegmentButtonItemOptionsArray仅支持保存2到5个按钮信息元素。

constructor

Phone12+PC/2in113+Tablet12+TV19+

constructor(elements: SegmentButtonItemTuple)

构造函数。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数:

展开
参数名 类型 必填 说明
elements SegmentButtonItemTuple 用于初始化数组的按钮信息元组,包含2到5个按钮选项元素,每个元素定义一个按钮的图标、文本等属性。
说明

SegmentButtonItemOptionsArray仅支持保存2到5个按钮信息元素。

push

Phone12+PC/2in113+Tablet12+TV19+

push(...items: SegmentButtonItemArray): number

在数组末尾添加新的元素,返回添加元素后数组的长度。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数:

展开
参数名 类型 必填 说明
items SegmentButtonItemArray

被添加的按钮信息数组。

默认值:不传入任何按钮信息元素。

返回值:

展开
类型 说明
number 添加元素后数组的长度。
说明

分段按钮组件数组仅支持保存2到5个按钮信息。当传入的元素数量导致数组超过5个,操作不执行并返回当前数组的长度。

pop

Phone12+PC/2in113+Tablet12+TV19+

pop(): SegmentButtonItemOptions | undefined

移除数组末尾最后一个元素,返回被移除的元素。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

返回值:

展开
类型 说明
SegmentButtonItemOptions | undefined 被移除的元素。
说明

分段按钮组件数组仅支持保存2到5个按钮信息。若移除后按钮数量少于2个,操作不执行并返回undefined,数组保持不变。

shift

Phone12+PC/2in113+Tablet12+TV19+

shift(): SegmentButtonItemOptions | undefined

移除数组开头第一个元素,返回被移除的元素。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

返回值:

展开
类型 说明
SegmentButtonItemOptions | undefined 被移除的元素。
说明

分段按钮组件数组仅支持保存2到5个按钮信息。若移除后按钮数量少于2个,操作不执行并返回undefined,数组保持不变。

unshift

Phone12+PC/2in113+Tablet12+TV19+

unshift(...items: SegmentButtonItemArray): number

在数组开头添加新的元素,返回添加元素后数组的长度。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数:

展开
参数名 类型 必填 说明
items SegmentButtonItemArray

添加的按钮信息数组。

默认值:不传入任何按钮信息元素。

返回值:

展开
类型 说明
number 添加元素后数组的长度。
说明

分段按钮组件数组仅支持保存2到5个按钮信息。当传入的元素数量导致数组超过5个,操作不执行并返回当前数组的长度。

splice

Phone12+PC/2in113+Tablet12+TV19+

splice(start: number, deleteCount: number, ...items: SegmentButtonItemOptions[]): SegmentButtonItemOptions[]

在数组中,删除从start位置开始的deleteCount数量的元素,并插入items中的元素,返回一个包含了被删除的元素的数组。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数:

展开
参数名 类型 必填 说明
start number 删除元素的起始位置,从0开始计数。
deleteCount number 删除元素的数量,取值范围大于等于0。若deleteCount超过数组剩余长度,则删除从start位置开始的所有剩余元素。
items SegmentButtonItemOptions[]

从start开始要加入到数组中的元素。

默认值:不指定任何元素,将从数组中删除元素。

返回值:

展开
类型 说明
SegmentButtonItemOptions[] 返回包含了被删除的元素的数组。
说明

分段按钮组件数组仅保存2到5个按钮信息。若操作结果会导致按钮数量少于2个或多于5个,操作将不执行并返回空数组。若删除操作导致数量少于2个,或添加操作导致数量超过5个,整个splice操作将不会生效,数组保持原状态。

create

Phone12+PC/2in113+Tablet12+TV19+

static create(elements: SegmentButtonItemTuple): SegmentButtonItemOptionsArray

创建一个SegmentButtonItemOptionsArray对象。与构造函数接受相同的参数,功能一致,可根据编码习惯选择使用。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数:

展开
参数名 类型 必填 说明
elements SegmentButtonItemTuple 用于初始化数组的按钮信息元组,包含2到5个按钮选项元素,每个元素定义一个按钮的图标、文本等属性。

返回值:

展开
类型 说明
SegmentButtonItemOptionsArray 返回创建的SegmentButtonItemOptionsArray对象,用于保存按钮信息的数组。
说明

SegmentButtonItemOptionsArray仅支持保存2到5个按钮信息元素。

TabSegmentButtonOptions

Phone12+PC/2in113+Tablet12+TV19+

页签类分段按钮选项。继承自TabSegmentButtonConstructionOptions

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
type "tab" 类型为页签类分段按钮。

CapsuleSegmentButtonOptions

Phone12+PC/2in113+Tablet12+TV19+

胶囊类分段按钮选项。继承自CapsuleSegmentButtonConstructionOptions

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
type "capsule" 类型为胶囊类分段按钮。

SegmentButtonTextItem

Phone12+PC/2in113+Tablet12+TV19+

文本按钮信息。

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
text ResourceStr

按钮文本。

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

accessibilityLevel13+ string

无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。

支持的值为:

"auto":当前组件可被无障碍辅助服务所识别。

"yes":当前组件可被无障碍辅助服务所识别。

"no":当前组件不可被无障碍辅助服务所识别。

"no-hide-descendants":当前组件及其所有子组件不可被无障碍辅助服务所识别。

默认值:"auto"

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

accessibilityDescription13+ ResourceStr

无障碍说明,用于为用户进一步说明当前组件,开发人员可为组件的该属性设置相对较详细的解释文本,帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果,尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性,则组件被选中时,先播报组件的文本属性,再播报无障碍说明属性的内容。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

SegmentButtonIconItem

Phone12+PC/2in113+Tablet12+TV19+

图标按钮信息。

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
icon ResourceStr

未选中态的按钮图标。

值为undefined时,不显示图标。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

iconAccessibilityText13+ ResourceStr

未选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

selectedIcon ResourceStr

选中态的按钮图标。

值为undefined时,不显示图标。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

selectedIconAccessibilityText13+ ResourceStr

选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

accessibilityLevel13+ string

无障碍重要性,用于控制当前组件是否可被无障碍辅助服务所识别。

支持的值为:

"auto":当前组件可被无障碍辅助服务所识别。

"yes":当前组件可被无障碍辅助服务所识别。

"no":当前组件不可被无障碍辅助服务所识别。

"no-hide-descendants":当前组件及其所有子组件不可被无障碍辅助服务所识别。

默认值:"auto"

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

accessibilityDescription13+ ResourceStr

无障碍说明,用于为用户进一步说明当前组件,开发人员可为组件的该属性设置相对较详细的解释文本,帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果,尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性,则组件被选中时,先播报组件的文本属性,再播报无障碍说明属性的内容。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

说明

未选中态的图标icon和选中态的图标selectedIcon都需设置,单独设置无效。

SegmentButtonIconTextItem

Phone12+PC/2in113+Tablet12+TV19+

图标与文本按钮信息。

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
icon ResourceStr

未选中态的按钮图标。

值为undefined时,不显示图标。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

iconAccessibilityText13+ ResourceStr

未选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

selectedIcon ResourceStr

选中态的按钮图标。

值为undefined时,不显示图标。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

selectedIconAccessibilityText13+ ResourceStr

选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

text ResourceStr

按钮文本。

值为undefined时,不显示文本内容。

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

accessibilityLevel13+ string

无障碍重要性,用于控制当前组件是否可被无障碍辅助服务所识别。

支持的值为:

"auto":当前组件可被无障碍辅助服务所识别。

"yes":当前组件可被无障碍辅助服务所识别。

"no":当前组件不可被无障碍辅助服务所识别。

"no-hide-descendants":当前组件及其所有子组件不可被无障碍辅助服务所识别。

默认值:"auto"

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

accessibilityDescription13+ ResourceStr

无障碍说明,用于为用户进一步说明当前组件,开发人员可为组件的该属性设置相对较详细的解释文本,帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果,尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性,则组件被选中时,先播报组件的文本属性,再播报无障碍说明属性的内容。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

说明

未选中态的图标icon和选中态的图标selectedIcon都需设置,单独设置无效。

SegmentButtonItemOptions

Phone12+PC/2in113+Tablet12+TV19+

分段按钮中的按钮选项。

装饰器类型: @Observed

属性

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
icon ResourceStr

未选中态的按钮图标。

默认值:不显示未选中态的按钮图标。

值为undefined时,按默认值处理。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

iconAccessibilityText13+ ResourceStr

未选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

selectedIcon ResourceStr

选中态的按钮图标。

默认值:不显示选中态按钮图标。

值为undefined时,按默认值处理。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

selectedIconAccessibilityText13+ ResourceStr

选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

text ResourceStr

按钮文本。

默认值:空字符串。

值为undefined时,按默认值处理。

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

accessibilityLevel13+ string

无障碍重要性,用于控制当前组件是否可被无障碍辅助服务所识别。

支持的值为:

"auto":当前组件可被无障碍辅助服务所识别。

"yes":当前组件可被无障碍辅助服务所识别。

"no":当前组件不可被无障碍辅助服务所识别。

"no-hide-descendants":当前组件及其所有子组件不可被无障碍辅助服务所识别。

默认值:"auto"

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

accessibilityDescription13+ ResourceStr

无障碍说明,用于为用户进一步说明当前组件,开发人员可为组件的该属性设置相对较详细的解释文本,帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果,尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性,则组件被选中时,先播报组件的文本属性,再播报无障碍说明属性的内容。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

说明

未选中态的图标icon和选中态的图标selectedIcon都需设置,单独设置无效。

constructor

Phone12+PC/2in113+Tablet12+TV19+

constructor(options: SegmentButtonItemOptionsConstructorOptions)

构造函数。

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

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

参数:

展开
参数名 类型 必填 说明
options SegmentButtonItemOptionsConstructorOptions 单个分段按钮的配置选项,包含图标、文本、无障碍属性等配置信息。

SegmentButtonItemOptionsConstructorOptions

Phone12+PC/2in113+Tablet12+TV19+

构造参数用于SegmentButtonItemOptions。

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

设备行为差异: 该接口在Wearable设备上使用时,应用程序运行异常,异常信息中提示接口未定义,在其他设备中可正常调用。

展开
名称 类型 只读 可选 说明
icon ResourceStr

未选中态的按钮图标。

默认值:不显示未选中态的按钮图标。

值为undefined时,按默认值处理。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

iconAccessibilityText13+ ResourceStr

未选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

selectedIcon ResourceStr

选中态的按钮图标。

默认值:不显示选中态的按钮图标。

值为undefined时,按默认值处理。

说明: icon和selectedIcon需同时设置,单独设置无效。

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

selectedIconAccessibilityText13+ ResourceStr

选中态按钮图标的无障碍文本。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

text ResourceStr

按钮文本。

默认值:空字符串。

值为undefined时,按默认值处理。

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

accessibilityLevel13+ string

无障碍重要性,用于控制当前组件是否可被无障碍辅助服务所识别。

支持的值为:

"auto":当前组件可被无障碍辅助服务所识别。

"yes":当前组件可被无障碍辅助服务所识别。

"no":当前组件不可被无障碍辅助服务所识别。

"no-hide-descendants":当前组件及其所有子组件不可被无障碍辅助服务所识别。

默认值:"auto"

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

accessibilityDescription13+ ResourceStr

无障碍说明,用于为用户进一步说明当前组件,开发人员可为组件的该属性设置相对较详细的解释文本,帮助用户理解将要执行的操作。如帮助用户理解将要执行的操作可能导致什么后果,尤其是当这些后果无法从组件本身属性与无障碍文本中了解到时。若组件既拥有文本属性又拥有无障碍说明属性,则组件被选中时,先播报组件的文本属性,再播报无障碍说明属性的内容。

默认值:空字符串。

值为undefined时,按默认值处理。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

说明

未选中态的图标icon和选中态的图标selectedIcon都需设置,单独设置无效。

示例

示例1(设置分段按钮的类型)

通过配置SegmentButtonOptions的tab和capsule,创建两种不同类型的分段按钮。

收起
自动换行
深色代码主题
复制
  1. import {
  2. ItemRestriction,
  3. SegmentButton,
  4. SegmentButtonItemTuple,
  5. SegmentButtonOptions,
  6. SegmentButtonTextItem
  7. } from '@kit.ArkUI';
  8. @Entry
  9. @Component
  10. struct Index {
  11. // 页签类分段按钮数组。
  12. @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
  13. buttons: [{ text: '页签按钮1' }, { text: '页签按钮2' }, {
  14. text: '页签按钮3'
  15. }] as ItemRestriction<SegmentButtonTextItem>,
  16. // 配置CommonSegmentButtonOptions,实现背景模糊样式。
  17. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  18. });
  19. // 胶囊类分段按钮数组。
  20. @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  21. buttons: [{ text: '单选按钮1' }, { text: '单选按钮2' }, { text: '单选按钮3' }] as SegmentButtonItemTuple,
  22. multiply: false,
  23. // 配置CommonSegmentButtonOptions,实现背景模糊样式。
  24. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  25. });
  26. // 可多选胶囊类分段按钮数组。
  27. @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  28. buttons: [{ text: '多选按钮1' }, { text: '多选按钮2' }, { text: '多选按钮3' }] as SegmentButtonItemTuple,
  29. multiply: true
  30. });
  31. // 胶囊类分段按钮带选中非选中图标数组。
  32. @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  33. buttons: [
  34. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  35. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  36. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  37. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
  38. ] as SegmentButtonItemTuple,
  39. multiply: false,
  40. // 配置CommonSegmentButtonOptions,实现背景模糊样式。
  41. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  42. });
  43. // 可多选胶囊类分段按钮带选中非选中图标数组。
  44. @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  45. buttons: [
  46. { text: '图标1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  47. { text: '图标2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  48. { text: '图标3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  49. { text: '图标4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  50. { text: '图标5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
  51. ] as SegmentButtonItemTuple,
  52. multiply: true
  53. });
  54. @State tabSelectedIndexes: number[] = [1];
  55. @State singleSelectCapsuleSelectedIndexes: number[] = [0];
  56. @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1];
  57. @State singleSelectIconCapsuleSelectedIndexes: number[] = [3];
  58. @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2];
  59. build() {
  60. Row() {
  61. Column() {
  62. Column({ space: 25 }) {
  63. SegmentButton({
  64. options: this.tabOptions,
  65. selectedIndexes: $tabSelectedIndexes
  66. })
  67. SegmentButton({
  68. options: this.singleSelectCapsuleOptions,
  69. selectedIndexes: $singleSelectCapsuleSelectedIndexes
  70. })
  71. SegmentButton({
  72. options: this.multiplySelectCapsuleOptions,
  73. selectedIndexes: $multiplySelectCapsuleSelectedIndexes
  74. })
  75. SegmentButton({
  76. options: this.iconCapsuleOptions,
  77. selectedIndexes: $singleSelectIconCapsuleSelectedIndexes
  78. })
  79. SegmentButton({
  80. options: this.iconTextCapsuleOptions,
  81. selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes
  82. })
  83. }.width('90%')
  84. }.width('100%')
  85. }.height('100%')
  86. }
  87. }

示例2(设置分段按钮样式)

通过配置CommonSegmentButtonOptions,实现自定义分段按钮的文本以及背景板样式。

收起
自动换行
深色代码主题
复制
  1. import {
  2. ItemRestriction,
  3. SegmentButton,
  4. SegmentButtonItemTuple,
  5. SegmentButtonOptions,
  6. SegmentButtonTextItem
  7. } from '@kit.ArkUI';
  8. @Entry
  9. @Component
  10. struct Index {
  11. @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
  12. buttons: [{ text: '页签按钮1' }, { text: '页签按钮2' }, {
  13. text: '页签按钮3'
  14. }] as ItemRestriction<SegmentButtonTextItem>,
  15. backgroundColor: 'rgb(213,213,213)',
  16. selectedBackgroundColor: 'rgb(112,112,112)', // 配置CommonSegmentButtonOptions,实现选中背景色
  17. textPadding: {
  18. top: 10,
  19. right: 10,
  20. bottom: 10,
  21. left: 10
  22. }, // 配置CommonSegmentButtonOptions,实现文字内边距
  23. });
  24. @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  25. buttons: [{ text: '单选按钮1' }, { text: '单选按钮2' }, { text: '单选按钮3' }] as SegmentButtonItemTuple,
  26. multiply: false,
  27. fontColor: 'rgb(0,74,175)', // 配置CommonSegmentButtonOptions,实现文字颜色
  28. selectedFontColor: 'rgb(247,247,247)', // 配置CommonSegmentButtonOptions,实现选中文字颜色
  29. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK // 配置CommonSegmentButtonOptions,实现背景模糊样式
  30. });
  31. @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  32. buttons: [{ text: '多选按钮1' }, { text: '多选按钮2' }, { text: '多选按钮3' }] as SegmentButtonItemTuple,
  33. multiply: true,
  34. fontSize: 18,
  35. selectedFontSize: 18,
  36. fontWeight: FontWeight.Bolder, // 配置CommonSegmentButtonOptions,实现文字粗细
  37. selectedFontWeight: FontWeight.Lighter, // 配置CommonSegmentButtonOptions,实现选中文字粗细
  38. });
  39. @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  40. buttons: [
  41. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  42. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  43. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  44. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
  45. ] as SegmentButtonItemTuple,
  46. multiply: false,
  47. imageSize: { width: 40, height: 40 },
  48. buttonPadding: {
  49. top: 6,
  50. right: 10,
  51. bottom: 6,
  52. left: 10
  53. },
  54. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  55. });
  56. @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  57. buttons: [
  58. { text: '图标1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  59. { text: '图标2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  60. { text: '图标3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  61. { text: '图标4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  62. { text: '图标5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
  63. ] as SegmentButtonItemTuple,
  64. multiply: true,
  65. imageSize: { width: 10, height: 10 },
  66. });
  67. @State tabSelectedIndexes: number[] = [0];
  68. @State singleSelectCapsuleSelectedIndexes: number[] = [0];
  69. @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1];
  70. @State singleSelectIconCapsuleSelectedIndexes: number[] = [3];
  71. @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2];
  72. build() {
  73. Row() {
  74. Column() {
  75. Column({ space: 20 }) {
  76. SegmentButton({ options: this.tabOptions, selectedIndexes: $tabSelectedIndexes })
  77. SegmentButton({
  78. options: this.singleSelectCapsuleOptions,
  79. selectedIndexes: $singleSelectCapsuleSelectedIndexes
  80. })
  81. SegmentButton({
  82. options: this.multiplySelectCapsuleOptions,
  83. selectedIndexes: $multiplySelectCapsuleSelectedIndexes
  84. })
  85. SegmentButton({
  86. options: this.iconCapsuleOptions,
  87. selectedIndexes: $singleSelectIconCapsuleSelectedIndexes
  88. })
  89. SegmentButton({
  90. options: this.iconTextCapsuleOptions,
  91. selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes
  92. })
  93. }.width('90%')
  94. }.width('100%')
  95. }.height('100%')
  96. }
  97. }

示例3(分段按钮数组处理)

该示例通过pop、shift、unshift等函数实现分段按钮数组的添加、移除等操作。

收起
自动换行
深色代码主题
复制
  1. import {
  2. SegmentButton,
  3. SegmentButtonOptions,
  4. SegmentButtonItemOptionsArray,
  5. SegmentButtonItemTuple,
  6. SegmentButtonItemOptions
  7. } from '@kit.ArkUI';
  8. @Entry
  9. @Component
  10. struct Index {
  11. // 胶囊类分段按钮数组。
  12. @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  13. buttons: [{ text: '1' }, { text: '2' }, { text: '3' },
  14. { text: '4' }, { text: '5' }] as SegmentButtonItemTuple,
  15. multiply: false,
  16. // 配置CommonSegmentButtonOptions,实现背景模糊样式。
  17. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  18. });
  19. @State capsuleSelectedIndexes: number[] = [0];
  20. build() {
  21. Row() {
  22. Column() {
  23. Column({ space: 10 }) {
  24. SegmentButton({
  25. options: this.singleSelectCapsuleOptions,
  26. selectedIndexes: $capsuleSelectedIndexes
  27. })
  28. // 点击“删除第一个按钮”,第一个按钮会删除。
  29. Button('删除第一个按钮')
  30. .onClick(() => {
  31. this.singleSelectCapsuleOptions.buttons.shift()
  32. })
  33. // 点击“删除最后一个按钮”,最后一个按钮会删除。
  34. Button('删除最后一个按钮')
  35. .onClick(() => {
  36. this.singleSelectCapsuleOptions.buttons.pop()
  37. })
  38. // 点击“末尾增加一个按钮push”,在按钮末尾会增加一个按钮。
  39. Button('末尾增加一个按钮push')
  40. .onClick(() => {
  41. this.singleSelectCapsuleOptions.buttons.push({ text: 'push' })
  42. })
  43. // 点击“开头增加一个按钮unshift”,在按钮开头会增加一个按钮。
  44. Button('开头增加一个按钮unshift')
  45. .onClick(() => {
  46. this.singleSelectCapsuleOptions.buttons.unshift(({ text: 'unshift' }))
  47. })
  48. // 点击“将按钮2、3替换为splice1、splice2”,按钮2、3会被替换成splice1、splice2。
  49. Button('将按钮2、3替换为splice1、splice2')
  50. .onClick(() => {
  51. this.singleSelectCapsuleOptions.buttons.splice(1, 2, new SegmentButtonItemOptions({
  52. text: 'splice1'
  53. }), new SegmentButtonItemOptions({ text: 'splice2' }))
  54. })
  55. // 点击“更改所有按钮文字”,按钮会由1、2、3、4、5替换成a、b、c、d、e。
  56. Button('更改所有按钮文字')
  57. .onClick(() => {
  58. this.singleSelectCapsuleOptions.buttons =
  59. SegmentButtonItemOptionsArray.create([{ text: 'a' }, { text: 'b' },
  60. { text: 'c' }, { text: 'd' }, { text: 'e' }])
  61. })
  62. }.width('90%')
  63. }.width('100%')
  64. }.height('100%')
  65. }
  66. }

示例4(设置镜像效果)

该示例通过配置direction属性设置分段按钮的布局方向,实现镜像效果。

收起
自动换行
深色代码主题
复制
  1. import { LengthMetrics, SegmentButton, SegmentButtonOptions } from '@kit.ArkUI';
  2. @Entry
  3. @Component
  4. struct Index {
  5. // 页签类分段按钮数组。
  6. @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
  7. buttons: [{ text: '页签按钮1' }, { text: '页签按钮2' }, {
  8. text: '页签按钮3'
  9. }],
  10. direction: Direction.Rtl, // 设置分段按钮的布局方向。
  11. backgroundColor: Color.Green, // 设置分段按钮的背景板颜色。
  12. selectedBackgroundColor: Color.Orange, // 设置分段按钮组件的按钮选中态背景板颜色。
  13. // 设置文本内边距。
  14. localizedTextPadding: {
  15. end: LengthMetrics.vp(10),
  16. start: LengthMetrics.vp(10)
  17. },
  18. });
  19. // 胶囊类分段按钮数组。
  20. @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  21. buttons: [{ text: '单选按钮1' }, { text: '单选按钮2' }, { text: '单选按钮3' }],
  22. multiply: false, // 设置分段按钮组件是否可以多选。
  23. direction: Direction.Rtl, // 设置分段按钮的布局方向。
  24. fontColor: Color.Black, // 设置分段按钮组件的按钮未选中态的文本颜色。
  25. selectedFontColor: Color.Yellow, // 设置分段按钮组件的按钮选中态的文本颜色。
  26. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK // 设置分段按钮组件的背景模糊材质。
  27. });
  28. // 胶囊类分段按钮数组。
  29. @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  30. buttons: [{ text: '多选按钮1' }, { text: '多选按钮2' }, { text: '多选按钮3' }],
  31. multiply: true, // 设置分段按钮组件是否可以多选。
  32. direction: Direction.Rtl, // 设置分段按钮的布局方向。
  33. fontSize: 18, // 设置分段按钮组件的按钮未选中态的字体大小。
  34. selectedFontSize: 18, // 设置分段按钮组件的按钮选中态的字体大小。
  35. fontWeight: FontWeight.Bolder, // 设置分段按钮组件的按钮未选中态的字体粗细。
  36. selectedFontWeight: FontWeight.Lighter, // 设置分段按钮组件的按钮选中态的字体粗细。
  37. });
  38. // 胶囊类分段按钮数组。
  39. @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  40. buttons: [
  41. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  42. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  43. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  44. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  45. { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
  46. ],
  47. multiply: false, // 设置分段按钮组件是否可以多选。
  48. direction: Direction.Rtl, // 设置分段按钮的布局方向。
  49. imageSize: { width: 40, height: 40 }, // 设置分段按钮组件的图片尺寸。
  50. // 设置分段按钮组件的按钮内边距,支持随布局方向(LTR/RTL)自适应。
  51. localizedButtonPadding: {
  52. end: LengthMetrics.vp(10),
  53. start: LengthMetrics.vp(10)
  54. },
  55. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK // 设置分段按钮组件的背景模糊材质。
  56. });
  57. @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  58. buttons: [
  59. { text: '图标1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  60. { text: '图标2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  61. { text: '图标3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  62. { text: '图标4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  63. { text: '图标5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
  64. ],
  65. multiply: true, // 设置分段按钮组件是否可以多选。
  66. direction: Direction.Rtl, // 设置分段按钮的布局方向。
  67. imageSize: { width: 10, height: 10 }, // 设置分段按钮组件的图片尺寸。
  68. });
  69. @State tabSelectedIndexes: number[] = [0];
  70. @State singleSelectCapsuleSelectedIndexes: number[] = [0];
  71. @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1];
  72. @State singleSelectIconCapsuleSelectedIndexes: number[] = [3];
  73. @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2];
  74. build() {
  75. Row() {
  76. Column() {
  77. Column({ space: 20 }) {
  78. SegmentButton({ options: this.tabOptions, selectedIndexes: $tabSelectedIndexes })
  79. SegmentButton({
  80. options: this.singleSelectCapsuleOptions,
  81. selectedIndexes: $singleSelectCapsuleSelectedIndexes
  82. })
  83. SegmentButton({
  84. options: this.multiplySelectCapsuleOptions,
  85. selectedIndexes: $multiplySelectCapsuleSelectedIndexes
  86. })
  87. SegmentButton({
  88. options: this.iconCapsuleOptions,
  89. selectedIndexes: $singleSelectIconCapsuleSelectedIndexes
  90. })
  91. SegmentButton({
  92. options: this.iconTextCapsuleOptions,
  93. selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes
  94. })
  95. }.width('90%')
  96. }.width('100%')
  97. }.height('100%')
  98. }
  99. }

示例5(设置无障碍朗读)

通过配置accessibilityLevel和selectedIconAccessibilityText等属性,实现了分段按钮的无障碍朗读功能。

收起
自动换行
深色代码主题
复制
  1. import {
  2. ItemRestriction,
  3. SegmentButton,
  4. SegmentButtonItemTuple,
  5. SegmentButtonOptions,
  6. SegmentButtonTextItem,
  7. SegmentButtonItemOptions
  8. } from '@kit.ArkUI';
  9. @Entry
  10. @Component
  11. struct Index {
  12. @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
  13. buttons: [{ text: '页签按钮1', accessibilityLevel: 'yes', accessibilityDescription: '页签按钮1 新手提醒' },
  14. { text: '页签按钮2', accessibilityLevel: 'yes', accessibilityDescription: '页签按钮2 新手提醒' },
  15. {
  16. text: '页签按钮3', accessibilityLevel: 'yes', accessibilityDescription: '页签按钮3 新手提醒'
  17. }] as ItemRestriction<SegmentButtonTextItem>,
  18. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  19. });
  20. @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  21. buttons: [
  22. {
  23. icon: $r('sys.media.ohos_ic_public_email'),
  24. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  25. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  26. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  27. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  28. accessibilityDescription: 'SegmentButtonIconItem 新手提醒' // 无障碍说明。
  29. },
  30. {
  31. icon: $r('sys.media.ohos_ic_public_email'),
  32. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  33. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  34. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  35. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  36. accessibilityDescription: 'SegmentButtonIconItem 新手提醒' // 无障碍说明。
  37. },
  38. {
  39. icon: $r('sys.media.ohos_ic_public_email'),
  40. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  41. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  42. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  43. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  44. accessibilityDescription: 'SegmentButtonIconItem 新手提醒' // 无障碍说明。
  45. },
  46. {
  47. icon: $r('sys.media.ohos_ic_public_email'),
  48. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  49. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  50. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  51. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  52. accessibilityDescription: 'SegmentButtonIconItem 新手提醒' // 无障碍说明。
  53. }
  54. ] as SegmentButtonItemTuple,
  55. multiply: false,
  56. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  57. });
  58. @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  59. buttons: [
  60. {
  61. text: '图标1',
  62. icon: $r('sys.media.ohos_ic_public_email'),
  63. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  64. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  65. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  66. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  67. accessibilityDescription: 'SegmentButtonIconTextItem 新手提醒' // 无障碍说明。
  68. },
  69. {
  70. text: '图标2',
  71. icon: $r('sys.media.ohos_ic_public_email'),
  72. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  73. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  74. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  75. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  76. accessibilityDescription: 'SegmentButtonIconTextItem 新手提醒' // 无障碍说明。
  77. },
  78. {
  79. text: '图标3',
  80. icon: $r('sys.media.ohos_ic_public_email'),
  81. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  82. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  83. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  84. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  85. accessibilityDescription: 'SegmentButtonIconTextItem 新手提醒' // 无障碍说明。
  86. },
  87. {
  88. text: '图标4',
  89. icon: $r('sys.media.ohos_ic_public_email'),
  90. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  91. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  92. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  93. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  94. accessibilityDescription: 'SegmentButtonIconTextItem 新手提醒' // 无障碍说明。
  95. }
  96. ] as SegmentButtonItemTuple,
  97. multiply: true
  98. });
  99. @State tabSelectedIndexes: number[] = [1];
  100. @State singleSelectIconCapsuleSelectedIndexes: number[] = [3];
  101. @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2];
  102. build() {
  103. Row() {
  104. Column() {
  105. Column({ space: 25 }) {
  106. SegmentButton({
  107. options: this.tabOptions,
  108. selectedIndexes: $tabSelectedIndexes
  109. })
  110. SegmentButton({
  111. options: this.iconCapsuleOptions,
  112. selectedIndexes: $singleSelectIconCapsuleSelectedIndexes
  113. })
  114. SegmentButton({
  115. options: this.iconTextCapsuleOptions,
  116. selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes
  117. })
  118. Button('将按钮2、3替换为splice1、splice2')
  119. .onClick(() => {
  120. this.iconTextCapsuleOptions.buttons.splice(1, 2, new SegmentButtonItemOptions({
  121. text: 'splice1', accessibilityLevel: 'yes', accessibilityDescription: 'SegmentButtonItemOptions 新手提醒'
  122. }), new SegmentButtonItemOptions({
  123. text: 'splice2',
  124. icon: $r('sys.media.ohos_ic_public_email'),
  125. iconAccessibilityText: '未选中图标无障碍文本', // 未选中态按钮图标的无障碍文本。
  126. selectedIcon: $r('sys.media.ohos_ic_public_clock'),
  127. selectedIconAccessibilityText: '选中图标无障碍文本', // 选中态按钮图标的无障碍文本。
  128. accessibilityLevel: 'yes', // 无障碍重要性,控制当前组件是否可被无障碍辅助服务识别。
  129. accessibilityDescription: 'SegmentButtonIconTextItem 新手提醒' // 无障碍说明。
  130. }))
  131. })
  132. }.width('90%')
  133. }.width('100%')
  134. }.height('100%')
  135. }
  136. }

示例6(设置自定义圆角)

该示例演示了如何为分段按钮组件设置自定义的边框圆角半径。

收起
自动换行
深色代码主题
复制
  1. import {
  2. BorderRadiusMode,
  3. ItemRestriction,
  4. LengthMetrics,
  5. SegmentButton,
  6. SegmentButtonOptions,
  7. SegmentButtonTextItem
  8. } from '@kit.ArkUI';
  9. @Entry
  10. @Component
  11. struct Index {
  12. @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
  13. buttons: [{ text: '页签按钮1' }, { text: '页签按钮2' }, {
  14. text: '页签按钮3'
  15. }] as ItemRestriction<SegmentButtonTextItem>,
  16. backgroundBlurStyle: BlurStyle.BACKGROUND_THICK,
  17. borderRadiusMode: BorderRadiusMode.CUSTOM, // 设置自定义的边框圆角半径
  18. backgroundBorderRadius: LengthMetrics.vp(8),
  19. itemBorderRadius: LengthMetrics.vp(6)
  20. });
  21. @State tabSelectedIndexes: number[] = [1];
  22. build() {
  23. Row() {
  24. Column() {
  25. Column({ space: 25 }) {
  26. SegmentButton({
  27. options: this.tabOptions,
  28. selectedIndexes: $tabSelectedIndexes,
  29. })
  30. }.width('90%')
  31. }.width('100%')
  32. }.height('100%')
  33. }
  34. }

示例7(开启SegmentButton的属性动画)

本示例展示了SegmentButton开启属性动画,即enableStateAnimation设置为true后,修改选中项编号selectedIndexes值会触发按钮切换动画。并且选中项编号相同的两个SegmentButton组件,是否开启属性动画,也会呈现不同的切换动画。

从API version 24开始,SegmentButton新增enableStateAnimation属性。

收起
自动换行
深色代码主题
复制
  1. import { SegmentButton, SegmentButtonItemTuple, SegmentButtonOptions } from '@kit.ArkUI';
  2. @Entry
  3. @Component
  4. struct Index {
  5. @State singleSelectTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  6. buttons: [
  7. { text: '单选按钮1' }, { text: '单选按钮2' }, { text: '单选按钮3' }
  8. ] as SegmentButtonItemTuple,
  9. multiply: false
  10. });
  11. @State textCapsuleSingleSelected: number[] = [0]; // 单选按钮的选中索引值,默认选中第一个。
  12. enableStateAnimation: boolean[] = [false, true];
  13. @State enableStateAnimationIndex: number = 0;
  14. @State currentSelectedIndex: number = 0; // 切换选中项的索引计数器。
  15. build() {
  16. Row() {
  17. Column() {
  18. Column({ space: 25 }) {
  19. // 动画仅在手动点击切换选中项时生效,非点击类操作修改选中项均无动画。
  20. SegmentButton({
  21. options: this.singleSelectTextCapsuleOptions,
  22. selectedIndexes: this.textCapsuleSingleSelected // 未开启属性动画。
  23. })
  24. Text('enableStateAnimation: ' + this.enableStateAnimation[this.enableStateAnimationIndex])
  25. .fontSize(18)
  26. .fontWeight(FontWeight.Bold)
  27. Row({ space: 10 }) {
  28. Button('false')
  29. .onClick(() => {
  30. this.enableStateAnimationIndex = 0;
  31. })
  32. Button('true')
  33. .onClick(() => {
  34. this.enableStateAnimationIndex = 1;
  35. })
  36. }
  37. .width('100%')
  38. .justifyContent(FlexAlign.Center)
  39. .margin({ bottom: 10 })
  40. // enableStateAnimation为true时,切换选中项会触发按钮切换动画。enableStateAnimation为false时,动画仅在手动点击切换选中项时生效,非点击类操作修改选中项均无动画。
  41. SegmentButton({
  42. options: this.singleSelectTextCapsuleOptions,
  43. selectedIndexes: this.textCapsuleSingleSelected,
  44. enableStateAnimation: this.enableStateAnimation[this.enableStateAnimationIndex] // 开启属性动画。
  45. })
  46. Button('change selectedIndexes')
  47. .onClick(() => {
  48. // 对选中项的索引值进行自增操作,若超出最大索引则重置为0。
  49. this.currentSelectedIndex = this.currentSelectedIndex < 2 ? this.currentSelectedIndex + 1 : 0;
  50. this.textCapsuleSingleSelected = [this.currentSelectedIndex];
  51. })
  52. }.width('90%')
  53. }.width('100%')
  54. }.height('100%')
  55. }
  56. }

示例8(设置背景板材质)

以下示例通过backgroundSystemMaterial属性,为分段按钮设置了透明的背景板材质、开启自动反色和交互形变效果,并自定义反馈光感的颜色。

从API版本26.0.0开始,SegmentButtonOptionsCommonSegmentButtonOptions中新增backgroundSystemMaterial属性。

收起
自动换行
深色代码主题
复制
  1. import {
  2. ItemRestriction,
  3. SegmentButton,
  4. SegmentButtonOptions,
  5. SegmentButtonTextItem,
  6. uiMaterial
  7. } from '@kit.ArkUI';
  8. @Entry
  9. @Component
  10. struct Index {
  11. @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
  12. buttons: [{ text: '页签按钮1' }, { text: '页签按钮2' }, {
  13. text: '页签按钮3'
  14. }] as ItemRestriction<SegmentButtonTextItem>,
  15. backgroundColor: Color.Transparent,
  16. // 将fontColor设置为特殊系统资源值,启用自动反色能力。
  17. fontColor: $r('sys.color.font_primary'),
  18. // 设置为系统材质样式为ULTRA_THIN,并开启自动反色和交互形变效果、自定义反馈光感的颜色。
  19. backgroundSystemMaterial: new uiMaterial.ImmersiveMaterial({
  20. style: uiMaterial.ImmersiveStyle.ULTRA_THIN,
  21. colorInvert: true,
  22. interactive: true,
  23. lightEffect: { color: undefined }
  24. })
  25. });
  26. @State tabSelectedIndexes: number[] = [0];
  27. @Builder
  28. NavigationTitle() {
  29. Column({ space: 20 }) {
  30. SegmentButton({
  31. options: this.tabOptions,
  32. selectedIndexes: $tabSelectedIndexes
  33. })
  34. }
  35. .width('100%')
  36. .height('20%')
  37. .padding(20)
  38. .linearGradient({
  39. angle: 90, // 渐变角度,90度是从左到右。
  40. colors: [
  41. ['#FF9A9E', 0.0], // 起始颜色及位置(0.0表示起点)。
  42. ['#FECFEF', 0.1], // 中间颜色及位置。
  43. ['#3B324C', 1.0] // 结束颜色及位置(1.0表示终点)。
  44. ]
  45. })
  46. }
  47. build() {
  48. Column() {
  49. Navigation() {
  50. // 页面内容
  51. }
  52. .title({ builder: this.NavigationTitle, height: '100%' })
  53. }.width('100%').height('100%')
  54. }
  55. }

示例9(监听SegmentButtonOptions内属性的变化)

SegmentButtonOptions使用了@Observed装饰器,SegmentButton组件通过@ObjectLink接收该对象。对于SegmentButtonOptions的一层基本类型属性(如fontColor、backgroundColor等),@Observed与@ObjectLink的联动机制已能观测到属性变化并触发UI刷新,无需额外处理。但对于SegmentButtonOptions中对象类型属性(如imageSize、buttonPadding等)的内部属性(如imageSize的width、height),属于更深层的嵌套属性,@State仅能观测到一层赋值变化,无法感知这类深层属性的修改,导致修改对象类型属性的内部属性时UI不会自动刷新。使用makeObserved接口对对象类型属性(如imageSize)进行包裹,可以为该对象的内部属性补充深度观察能力,使得修改内部属性(如width、height)时,框架能够监听到变化并触发UI刷新。makeObserved接口的详细说明请参考makeObserved接口:将非观察数据变为可观察数据

以下示例对比了两种场景:点击“修改fontColor颜色”按钮修改iconTextCapsuleOptions的fontColor属性(一层基本类型属性,已通过@Observed与@ObjectLink支持观测),UI自动刷新;点击“修改图标大小”按钮修改iconTextCapsuleOptions.imageSize的width和height属性(imageSize对象的内部属性,需通过UIUtils.makeObserved包裹imageSize才能观测),UI同样自动刷新。

收起
自动换行
深色代码主题
复制
  1. import {
  2. SegmentButton,
  3. SegmentButtonOptions,
  4. SegmentButtonItemTuple,
  5. UIUtils
  6. } from '@kit.ArkUI';
  7. @Entry
  8. @Component
  9. struct Index {
  10. @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
  11. buttons: [
  12. { text: '图标1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  13. { text: '图标2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  14. { text: '图标3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  15. { text: '图标4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
  16. { text: '图标5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
  17. ] as SegmentButtonItemTuple,
  18. multiply: false,
  19. // 使用UIUtils.makeObserved包裹imageSize,使内部属性width和height可被观测。
  20. imageSize: UIUtils.makeObserved({ width: 30, height: 30 })
  21. });
  22. @State selectedIndexes: number[] = [0];
  23. @State currentFontColor: ResourceColor = Color.Blue;
  24. build() {
  25. Column({ space: 20 }) {
  26. SegmentButton({
  27. options: this.iconTextCapsuleOptions,
  28. selectedIndexes: $selectedIndexes
  29. })
  30. // 一层基本类型属性,已通过@Observed与@ObjectLink支持this.iconTextCapsuleOptions.fontColor的观测,UI自动刷新。
  31. Button('修改fontColor颜色')
  32. .onClick(() => {
  33. if (this.currentFontColor === Color.Blue) {
  34. this.currentFontColor = Color.Red;
  35. } else {
  36. this.currentFontColor = Color.Blue;
  37. }
  38. this.iconTextCapsuleOptions.fontColor = this.currentFontColor;
  39. })
  40. // 修改imageSize的内部属性,由于makeObserved包裹,UI会自动刷新。
  41. Button('修改图标大小')
  42. .onClick(() => {
  43. this.iconTextCapsuleOptions.imageSize.width = 10;
  44. this.iconTextCapsuleOptions.imageSize.height = 10;
  45. })
  46. }
  47. .width('100%')
  48. .height('50%')
  49. .padding({ top: 20 })
  50. }
  51. }

在 API参考 中进行搜索
请输入您想要搜索的关键词