1# SegmentButton 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @xieziang--> 5<!--Designer: @youzhi92--> 6<!--Tester: @TerryTsao--> 7<!--Adviser: @HelloCrease--> 8 9**SegmentButton** is a versatile component that organizes related options into visually grouped buttons. It supports three variants: tab-style, capsule-style single-select, and capsule-style multi-select. 10 11>**NOTE** 12> 13>This component is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version. 14> 15 16## Modules to Import 17 18``` 19import { SegmentButton, SegmentButtonOptions, SegmentButtonItemOptionsArray } from '@kit.ArkUI'; 20``` 21 22## Child Components 23 24Not supported 25 26## SegmentButton 27 28SegmentButton({ options: SegmentButtonOptions, selectedIndexes: number[], onItemClicked: Callback\<number\>, maxFontScale: number \| Resource }) 29 30**Decorator**: @Component 31 32**System capability**: SystemCapability.ArkUI.ArkUI.Full 33 34**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 35 36| Name | Type | Mandatory| Decorator | Description | 37| --------------- | --------------------------------------------- | ---- | ----------- | ------------------------------------------------------------ | 38| options | [SegmentButtonOptions](#segmentbuttonoptions) | Yes | @ObjectLink | Options of the **SegmentButton** component.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 39| selectedIndexes | number[] | Yes | @Link | Indexes of selected items of the **SegmentButton**. The index is zero-based and increments by 1.<br>**NOTE**<br>**selectedIndexes** is decorated with [@Link](../../../ui/state-management/arkts-link.md) to implement parent-child two-way synchronization. If no items are selected, an empty array **[]** can be passed in. <br>**Atomic service API**: This API can be used in atomic services since API version 12.| 40| onItemClicked<sup>13+</sup> | Callback\<number\> | No| - | Callback invoked when an item in the **SegmentButton** is clicked. The index of the clicked item is passed in as the parameter.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 41| maxFontScale<sup>14+</sup> | number \| [Resource](ts-types.md#resource) | Yes| @Prop | Maximum font scale for the text in the **SegmentButton**.<br>Default value: **1**<br>Value range: [1, 2]<br>**NOTE**<br>Values less than 1 are treated as 1, and values greater than 2 are treated as 2.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 42 43>**NOTE** 44> 45>The **SegmentButton** component does not support the universal attributes. The component takes up the maximum width allowed by the content area, and evenly allocates the width among its items. It adapts its height automatically to the content (text and image), the minimum height being 28 vp. 46 47## SegmentButtonOptions 48 49>**NOTE** 50> 51> The component does not support custom font type settings. 52 53Provides initial data and custom properties for the **SegmentButton** component. 54 55**Decorator Type**: @Observed 56 57**System capability**: SystemCapability.ArkUI.ArkUI.Full 58 59**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 60 61### Properties 62 63| Name | Type | Mandatory | Description | 64| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 65| type | 'tab' \| 'capsule' | Yes | Type of the **SegmentButton** component.<br>**NOTE**<br>**'tab'**: tab-style segmented buttons, designed for page or content section switching.<br>**'capsule'**: capsule-style segmented buttons, suitable for single or multiple selection scenarios.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 66| multiply | boolean | Yes | Whether multiple items can be selected.<br>**NOTE**<br>Default value: **false**.<br>**true**: Multiple items can be selected.<br>**false**: Multiple items cannot be selected. For the **SegmentButton** component consisting of tab-style buttons, only one item can be selected. In this case, setting **multiply** to **true** does not take effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 67| buttons | [SegmentButtonItemOptionsArray](#segmentbuttonitemoptionsarray) | Yes| Button information, including the icon and text.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 68| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the unselected item.<br>Default value: **$r('sys.color.ohos_id_color_text_secondary')**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 69| selectedFontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the selected item.<br>Default value: **$r('sys.color.ohos_id_color_text_primary')** when **type** is **"tab"**<br>and **$r('sys.color.ohos_id_color_foreground_contrary')** when **type** is **"capsule"**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 70| fontSize | [DimensionNoPercentage](#dimensionnopercentage) | No | Font size of the unselected item. It cannot be set in percentage.<br>Default value: **$r('sys.float.ohos_id_text_size_body2')**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 71| selectedFontSize | [DimensionNoPercentage](#dimensionnopercentage) | No | Font size of the selected item. It cannot be set in percentage.<br>Default value: **$r('sys.float.ohos_id_text_size_body2')**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 72| fontWeight | [FontWeight](ts-appendix-enums.md#fontweight) | No | Font weight of the unselected item.<br>Default value: **FontWeight.Regular**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 73| selectedFontWeight | [FontWeight](ts-appendix-enums.md#fontweight) | No | Font weight of the selected item.<br>Default value: **FontWeight.Medium**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 74| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the unselected item.<br>Default value: **$r('sys.color.ohos_id_color_button_normal')**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 75| selectedBackgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the selected item.<br>Default value: **$r('sys.color.ohos_id_color_foreground_contrary')** when **type** is **"tab"**<br>and **$r('sys.color.ohos_id_color_emphasize')** when **type** is **"capsule"**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 76| imageSize | [SizeOptions](ts-types.md#sizeoptions) | No | Image size.<br>Default value: { width: 24, height: 24 }.<br>**NOTE**<br>This property is effective only for buttons that contain icons.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 77| buttonPadding | [Padding](ts-types.md#padding) \| [Dimension](ts-types.md#dimension10) | No| Button margin.<br>Default value: **{ top: 4, right: 8, bottom: 4, left: 8 }** for icon buttons and text buttons, and **{ top: 6, right: 8, bottom: 6, left: 8 }** for icon+text buttons.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 78| textPadding | [Padding](ts-types.md#padding) \| [Dimension](ts-types.md#dimension10) | No| Text padding.<br>Default value: **0**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 79| localizedButtonPadding<sup>12+</sup> | [LocalizedPadding](ts-types.md#localizedpadding12) | No | Button padding.<br>Default value:<br>Text-only buttons and icon-only buttons: **{ top: LengthMetrics.vp(4), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(4), start: LengthMetrics.vp(8) }**<br>Buttons with both an icon and text: **{ top: LengthMetrics.vp(6), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(6), start: LengthMetrics.vp(8) }**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 80| localizedTextPadding<sup>12+</sup> | [LocalizedPadding](ts-types.md#localizedpadding12) | No | Text padding.<br>Default value: **0**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 81| direction<sup>12+</sup> | [Direction](ts-appendix-enums.md#direction) | No | Layout direction.<br>Default value: **Direction.Auto**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 82| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No | Background blur style applied between the content and the background.<br>Default value: **BlurStyle.NONE**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 83| borderRadiusMode<sup>20+</sup> | [BorderRadiusMode](#borderradiusmode20) | No| Border radius mode, used to control the border radius calculation method.<br>Default value: **BorderRadiusMode.DEFAULT**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 84| backgroundBorderRadius<sup>20+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Container border radius.<br>**NOTE**<br>This attribute takes effect only when **borderRadiusMode** is set to **BorderRadiusMode.CUSTOM**.<br>For capsule-style multi-select segmented buttons (with **type** being **'capsule'** and **multiply** being **true**), this attribute does not take effect and **itemBorderRadius** must be used to set the border radius.<br>The maximum value for the border radius is half of the component's width or height, and percentage values are not supported.<br>Default value: **$r('sys.float.segmentbutton_container_shape')**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 85| itemBorderRadius<sup>20+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Individual button border radius.<br>**NOTE**<br>This attribute takes effect only when **borderRadiusMode** is set to **BorderRadiusMode.CUSTOM**.<br>For capsule-style multi-select segmented buttons (with **type** being **'capsule'** and **multiply** being **true**), this attribute only affects end items.<br>The maximum value for the border radius is half of the component's width or height, and percentage values are not supported.<br>Default value: **$r('sys.float.segmentbutton_selected_background_shape')**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 86 87### constructor 88 89constructor(options: TabSegmentButtonOptions | CapsuleSegmentButtonOptions) 90 91A constructor used to create a **SegmentButton** instance with specified configuration options. 92 93**Atomic service API**: This API can be used in atomic services since API version 12. 94 95**System capability**: SystemCapability.ArkUI.ArkUI.Full 96 97**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 98 99**Parameters** 100 101| Name | Type | Mandatory| Description | 102| ------- | ------------------------------------------------------------ | ---- | -------------------- | 103| options | [TabSegmentButtonOptions](#tabsegmentbuttonoptions) \| [CapsuleSegmentButtonOptions](#capsulesegmentbuttonoptions) | Yes| Configuration options for tab-style or capsule-style segmented buttons.| 104 105### tab 106 107static tab(options: TabSegmentButtonConstructionOptions): SegmentButtonOptions 108 109Creates a **SegmentButtonOptions** object specifically for tab-style segmented buttons. 110 111**Atomic service API**: This API can be used in atomic services since API version 12. 112 113**System capability**: SystemCapability.ArkUI.ArkUI.Full 114 115**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 116 117**Parameters** 118 119| Name | Type | Mandatory| Description | 120| ------- | ------------------------------------------------------------ | ---- | -------------------- | 121| options | [TabSegmentButtonConstructionOptions](#tabsegmentbuttonconstructionoptions) | Yes | Configuration options for tab-style segmented buttons.| 122 123**Return value** 124 125| Type | Description | 126| ------ | ------------------------ | 127| [SegmentButtonOptions](#segmentbuttonoptions) | **SegmentButtonOptions** object.| 128 129### capsule 130 131static capsule(options: CapsuleSegmentButtonConstructionOptions): SegmentButtonOptions 132 133Creates a **SegmentButtonOptions** object specifically for capsule-style segmented buttons. 134 135**Atomic service API**: This API can be used in atomic services since API version 12. 136 137**System capability**: SystemCapability.ArkUI.ArkUI.Full 138 139**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 140 141**Parameters** 142 143| Name | Type | Mandatory| Description | 144| ------- | ------------------------------------------------------------ | ---- | --------------------------- | 145| options | [CapsuleSegmentButtonConstructionOptions](#capsulesegmentbuttonconstructionoptions) | Yes | Configuration options for capsule-style segmented buttons.| 146 147**Return value** 148 149| Type | Description | 150| ------ | ------------------------ | 151| [SegmentButtonOptions](#segmentbuttonoptions) | **SegmentButtonOptions** object.| 152 153## DimensionNoPercentage 154 155type DimensionNoPercentage = PX | VP | FP | LPX | Resource 156 157Represents the length union type that does not support values in percentage. 158 159**Atomic service API**: This API can be used in atomic services since API version 12. 160 161**System capability**: SystemCapability.ArkUI.ArkUI.Full 162 163**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 164 165| Type | Description | 166| -------------------------------- | --------------------------------------------- | 167| [PX](ts-types.md#px10) | Length in px. | 168| [VP](ts-types.md#vp10) | Length in vp. | 169| [FP](ts-types.md#fp10) | Length in fp. | 170| [LPX](ts-types.md#lpx10) | Length in lpx.| 171| [Resource](ts-types.md#resource) | Resource reference type, which is used to set the value of a component attribute. | 172 173## CommonSegmentButtonOptions 174 175Defines the customizable properties for the **SegmentButton** component. 176 177**System capability**: SystemCapability.ArkUI.ArkUI.Full 178 179**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 180 181### Properties 182 183| Name | Type | Mandatory | Description | 184| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 185| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the unselected item.<br>Default value: **$r('sys.color.ohos_id_color_text_secondary')**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 186| selectedFontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the selected item.<br>Default value: **$r('sys.color.ohos_id_color_text_primary')** when **type** is **"tab"**<br>and **$r('sys.color.ohos_id_color_foreground_contrary')** when **type** is **"capsule"**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 187| fontSize | [DimensionNoPercentage](#dimensionnopercentage) | No | Font size of the unselected item. It cannot be set in percentage.<br>Default value: **$r('sys.float.ohos_id_text_size_body2')**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 188| selectedFontSize | [DimensionNoPercentage](#dimensionnopercentage) | No | Font size of the selected item. It cannot be set in percentage.<br>Default value: **$r('sys.float.ohos_id_text_size_body2')**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 189| fontWeight | [FontWeight](ts-appendix-enums.md#fontweight) | No | Font weight of the unselected item.<br>Default value: **FontWeight.Regular**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 190| selectedFontWeight | [FontWeight](ts-appendix-enums.md#fontweight) | No | Font weight of the selected item.<br>Default value: **FontWeight.Medium**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 191| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the unselected item.<br>Default value: **$r('sys.color.ohos_id_color_button_normal')**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 192| selectedBackgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the selected item.<br>Default value: **$r('sys.color.ohos_id_color_foreground_contrary')** when **type** is **"tab"**<br>and **$r('sys.color.ohos_id_color_emphasize')** when **type** is **"capsule"**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 193| imageSize | [SizeOptions](ts-types.md#sizeoptions) | No | Image size.<br>Default value: { width: 24, height: 24 }.<br>**NOTE**<br>This property is effective only for buttons that contain icons.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 194| buttonPadding | [Padding](ts-types.md#padding) \| [Dimension](ts-types.md#dimension10) | No| Button margin.<br>Default value: **{ top: 4, right: 8, bottom: 4, left: 8 }** for icon buttons and text buttons, and **{ top: 6, right: 8, bottom: 6, left: 8 }** for icon+text buttons.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 195| textPadding | [Padding](ts-types.md#padding) \| [Dimension](ts-types.md#dimension10) | No| Text padding.<br>Default value: **0**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 196| localizedButtonPadding<sup>12+</sup> | [LocalizedPadding](ts-types.md#localizedpadding12) | No | Button padding.<br>Default value:<br>Text-only buttons and icon-only buttons: **{ top: LengthMetrics.vp(4), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(4), start: LengthMetrics.vp(8) }**<br>Buttons with both an icon and text: **{ top: LengthMetrics.vp(6), end: LengthMetrics.vp(8), bottom: LengthMetrics.vp(6), start: LengthMetrics.vp(8) }**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 197| localizedTextPadding<sup>12+</sup> | [LocalizedPadding](ts-types.md#localizedpadding12) | No | Text padding.<br>Default value: **0**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 198| direction<sup>12+</sup> | [Direction](ts-appendix-enums.md#direction) | No | Layout direction.<br>Default value: **Direction.Auto**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 199| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No | Background blur style applied between the content and the background.<br>Default value: **BlurStyle.NONE**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 200| borderRadiusMode<sup>20+</sup> | [BorderRadiusMode](#borderradiusmode20) | No| Border radius mode, used to control the border radius calculation method.<br>Default value: **BorderRadiusMode.DEFAULT**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 201| backgroundBorderRadius<sup>20+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Container border radius.<br>**NOTE**<br>This attribute takes effect only when **borderRadiusMode** is set to **BorderRadiusMode.CUSTOM**.<br>For capsule-style multi-select segmented buttons (with **type** being **'capsule'** and **multiply** being **true**), this attribute does not take effect and **itemBorderRadius** must be used to set the border radius.<br>The maximum value for the border radius is half of the component's width or height, and percentage values are not supported.<br>Default value: **$r('sys.float.segmentbutton_container_shape')**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 202| itemBorderRadius<sup>20+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Individual button border radius.<br>**NOTE**<br>This attribute takes effect only when **borderRadiusMode** is set to **BorderRadiusMode.CUSTOM**.<br>For capsule-style multi-select segmented buttons (with **type** being **'capsule'** and **multiply** being **true**), this attribute only affects end items.<br>The maximum value for the border radius is half of the component's width or height, and percentage values are not supported.<br>Default value: **$r('sys.float.segmentbutton_selected_background_shape')**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 203 204## BorderRadiusMode<sup>20+</sup> 205 206Enumerates the border radius modes for the **SegmentButton** component, which are used to control the border radius calculation method. 207 208**Atomic service API**: This API can be used in atomic services since API version 20. 209 210**System capability**: SystemCapability.ArkUI.ArkUI.Full 211 212**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 213 214| Name |Value| Description | 215| ------- | - |-------------------------------- | 216| DEFAULT | 0 |Default mode, where the framework automatically calculates the border radius.| 217| CUSTOM | 1 |Custom mode, where the border radius is set by the developer.| 218 219## TabSegmentButtonConstructionOptions 220 221Represents configuration options for creating a **SegmentButton** component consisting of tab-style segmented buttons. 222 223Inherits from [CommonSegmentButtonOptions](#commonsegmentbuttonoptions). 224 225**Atomic service API**: This API can be used in atomic services since API version 12. 226 227**System capability**: SystemCapability.ArkUI.ArkUI.Full 228 229**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 230 231### Properties 232 233| Name | Type | Mandatory| Description | 234| ------- | ------------------------------------------------------------ | ---- | ---------- | 235| buttons | [ItemRestriction](#itemrestriction)\<[SegmentButtonTextItem](#segmentbuttontextitem)> | Yes | Button information.| 236 237## CapsuleSegmentButtonConstructionOptions 238 239Represents configuration options for creating a **SegmentButton** component consisting of capsule-style segmented buttons. 240 241Inherits from [CommonSegmentButtonOptions](#commonsegmentbuttonoptions). 242 243**Atomic service API**: This API can be used in atomic services since API version 12. 244 245**System capability**: SystemCapability.ArkUI.ArkUI.Full 246 247**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 248 249### Properties 250 251| Name | Type | Mandatory| Description | 252| -------- | ------------------------------------------------- | ---- | ----------------------------- | 253| buttons | [SegmentButtonItemTuple](#segmentbuttonitemtuple) | Yes | Button information. | 254| multiply | boolean | No | Whether multi-selection is allowed. <br>**true**: Multi-selection is allowed.<br>**false**: Multi-selection is not allowed. Default value: **false**.| 255 256## ItemRestriction 257 258type ItemRestriction\<T> = [T, T, T?, T?, T?] 259 260Represents a tuple used to store button information. 261 262**Atomic service API**: This API can be used in atomic services since API version 12. 263 264**System capability**: SystemCapability.ArkUI.ArkUI.Full 265 266**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 267 268| Type | Description | 269| ----------------------------------------- | --------------------------------- | 270|[T, T, T?, T?, T?] | A tuple that contains two to five elements of the same type.| 271 272>**NOTE** 273> 274>A **SegmentButton** component supports two to five buttons. 275 276## SegmentButtonItemTuple 277 278type SegmentButtonItemTuple = ItemRestriction\<SegmentButtonTextItem> | ItemRestriction\<SegmentButtonIconItem> | ItemRestriction\<SegmentButtonIconTextItem> 279 280Represents the tuple union type used to store button information. 281 282**Atomic service API**: This API can be used in atomic services since API version 12. 283 284**System capability**: SystemCapability.ArkUI.ArkUI.Full 285 286**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 287 288| Type | Description | 289| ------------------------------------------------------------ | ------------------------- | 290| [ItemRestriction](#itemrestriction)\<[SegmentButtonTextItem](#segmentbuttontextitem)\> | A tuple of text-only button information. | 291| [ItemRestriction](#itemrestriction)\<[SegmentButtonIconItem](#segmentbuttoniconitem)\> | A tuple of icon-only button information. | 292| [ItemRestriction](#itemrestriction)\<[SegmentButtonIconTextItem](#segmentbuttonicontextitem)\> | A tuple of icon and text button information.| 293 294## SegmentButtonItemArray 295 296type SegmentButtonItemArray = Array\<SegmentButtonTextItem> | Array\<SegmentButtonIconItem> | Array\<SegmentButtonIconTextItem> 297 298Represents the array union type used to store button information. 299 300**Atomic service API**: This API can be used in atomic services since API version 12. 301 302**System capability**: SystemCapability.ArkUI.ArkUI.Full 303 304**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 305 306| Type | Description | 307| ------------------------------------------------------------ | ------------------------- | 308| Array\<[SegmentButtonTextItem](#segmentbuttontextitem)\> | An array of text-only button information. | 309| Array\<[SegmentButtonIconItem](#segmentbuttoniconitem)\> | An array of icon-only button information. | 310| Array\<[SegmentButtonIconTextItem](#segmentbuttonicontextitem)\> | An array of icon and text button information.| 311 312## SegmentButtonItemOptionsArray 313 314Represents an array for storing button information. 315 316**Decorator Type**: @Observed 317 318>**NOTE** 319> 320>A **SegmentButton** component supports two to five buttons. As such, a **SegmentButtonItemOptionsArray** object stores information about only two to five buttons. 321 322### constructor 323 324constructor(elements: SegmentButtonItemTuple) 325 326A constructor used to create a **SegmentButtonItemOptionsArray** instance. 327 328**Atomic service API**: This API can be used in atomic services since API version 12. 329 330**System capability**: SystemCapability.ArkUI.ArkUI.Full 331 332**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 333 334**Parameters** 335 336 337| Name | Type | Mandatory| Description | 338| -------- | ------------------------------------------------- | ---- | ---------- | 339| elements | [SegmentButtonItemTuple](#segmentbuttonitemtuple) | Yes | Button information.| 340 341### push 342 343push(...items: SegmentButtonItemArray): number 344 345Adds the specified elements to the end of this array and returns the new length of the array. 346 347**Atomic service API**: This API can be used in atomic services since API version 12. 348 349**System capability**: SystemCapability.ArkUI.ArkUI.Full 350 351**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 352 353**Parameters** 354 355 356| Name| Type | Mandatory| Description | 357| ------ | ------------------------------------------------- | ---- | ---------------------- | 358| items | [SegmentButtonItemArray](#segmentbuttonitemarray) | Yes | Elements to add to the end of the array.| 359 360**Return value** 361 362| Type | Description | 363| ------ | ------------------------ | 364| number | Length of the array after the elements are added.| 365 366>**NOTE** 367> 368>A **SegmentButton** component supports two to five buttons. As such, a **SegmentButtonItemOptionsArray** object stores information about only two to five buttons. If the number limit is reached, this API will not work. 369 370### pop 371 372pop(): SegmentButtonItemOptions | undefined 373 374Removes the last element from this array and returns that element. 375 376**Atomic service API**: This API can be used in atomic services since API version 12. 377 378**System capability**: SystemCapability.ArkUI.ArkUI.Full 379 380**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 381 382**Return value** 383 384| Type | Description | 385| ------------------------------------------------------------ | -------------- | 386| [SegmentButtonItemOptions](#segmentbuttonitemoptions) \| undefined | Element removed from the array.| 387 388>**NOTE** 389> 390>A **SegmentButton** component supports two to five buttons. As such, a **SegmentButtonItemOptionsArray** object stores information about only two to five buttons. If the number limit is reached, this API will not work. 391 392### shift 393 394shift(): SegmentButtonItemOptions | undefined 395 396Removes the first element from this array and returns that element. 397 398**Atomic service API**: This API can be used in atomic services since API version 12. 399 400**System capability**: SystemCapability.ArkUI.ArkUI.Full 401 402**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 403 404**Return value** 405 406| Type | Description | 407| ------------------------------------------------------------ | -------------- | 408| [SegmentButtonItemOptions](#segmentbuttonitemoptions) \| undefined | Element removed from the array.| 409 410>**NOTE** 411> 412>A **SegmentButton** component supports two to five buttons. As such, a **SegmentButtonItemOptionsArray** object stores information about only two to five buttons. If the number limit is reached, this API will not work. 413 414### unshift 415 416unshift(...items: SegmentButtonItemArray): number 417 418Adds the specified elements to the beginning of this array and returns the new length of the array. 419 420**Atomic service API**: This API can be used in atomic services since API version 12. 421 422**System capability**: SystemCapability.ArkUI.ArkUI.Full 423 424**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 425 426**Parameters** 427 428 429| Name | Type | Mandatory| Description | 430| ----- | ------------------------------------------------- | ---- | -------------------- | 431| items | [SegmentButtonItemArray](#segmentbuttonitemarray) | Yes | Elements to add to the beginning of the array.| 432 433**Return value** 434 435| Type | Description | 436| ------ | ---------------------- | 437| number | Length of the array after the elements are added.| 438 439>**NOTE** 440> 441>A **SegmentButton** component supports two to five buttons. As such, a **SegmentButtonItemOptionsArray** object stores information about only two to five buttons. If the number limit is reached, this API will not work. 442 443### splice 444 445splice(start: number, deleteCount: number, ...items: SegmentButtonItemOptions[]): SegmentButtonItemOptions[] 446 447Changes the contents of this array by removing the specified number of elements from the specified position and adding new elements in place. This API returns an array containing the removed elements. 448 449**Atomic service API**: This API can be used in atomic services since API version 12. 450 451**System capability**: SystemCapability.ArkUI.ArkUI.Full 452 453**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 454 455**Parameters** 456 457 458| Name | Type | Mandatory| Description | 459| ----------- | ------------------------------------------------------- | ---- | -------------------- | 460| start | number | Yes | Index of the position starting from which elements are to be removed.| 461| deleteCount | number | Yes | Number of elements to remove. | 462| items | [SegmentButtonItemOptions](#segmentbuttonitemoptions)[] | No | Elements to add to the array. | 463 464**Return value** 465 466| Type | Description | 467| ------------------------------------------------------- | ------------------------------ | 468| [SegmentButtonItemOptions](#segmentbuttonitemoptions)[] | An array containing the removed elements.| 469 470>**NOTE** 471> 472>A **SegmentButton** component supports two to five buttons. As such, a **SegmentButtonItemOptionsArray** object stores information about only two to five buttons. If the number limit is reached, this API will not work. 473 474### create 475 476static create(elements: SegmentButtonItemTuple): SegmentButtonItemOptionsArray 477 478Creates a **SegmentButtonItemOptionsArray** object. 479 480**Atomic service API**: This API can be used in atomic services since API version 12. 481 482**System capability**: SystemCapability.ArkUI.ArkUI.Full 483 484**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 485 486**Parameters** 487 488 489| Name | Type | Mandatory| Description | 490| -------- | ------------------------------------------------- | ---- | ---------- | 491| elements | [SegmentButtonItemTuple](#segmentbuttonitemtuple) | Yes | Button information.| 492 493**Return value** 494 495| Type | Description | 496| ------------------------------------------------------------ | ----------------------------------------- | 497| [SegmentButtonItemOptionsArray](#segmentbuttonitemoptionsarray) | Created **SegmentButtonItemOptionsArray** object.| 498 499## TabSegmentButtonOptions 500 501Provides configuration options for tab-style segmented buttons. Inherits from [TabSegmentButtonConstructionOptions](#tabsegmentbuttonconstructionoptions). 502 503**Atomic service API**: This API can be used in atomic services since API version 12. 504 505**System capability**: SystemCapability.ArkUI.ArkUI.Full 506 507**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 508 509| Name| Type | Mandatory| Description | 510| ---- | ----- | ---- | ---------------------- | 511| type | 'tab' | Yes | Type of the segmented buttons, which is **'tab'** in this case.| 512 513## CapsuleSegmentButtonOptions 514 515Provides configuration options for capsule-style segmented buttons. Inherits from [CapsuleSegmentButtonConstructionOptions](#capsulesegmentbuttonconstructionoptions). 516 517**Atomic service API**: This API can be used in atomic services since API version 12. 518 519**System capability**: SystemCapability.ArkUI.ArkUI.Full 520 521**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 522 523| Name| Type | Mandatory| Description | 524| ---- | --------- | ---- | ----------------------------- | 525| type | 'capsule' | Yes | Type of the segmented buttons, which is **'capsule'** in this case.| 526 527## SegmentButtonTextItem 528 529Provides text button information. 530 531**System capability**: SystemCapability.ArkUI.ArkUI.Full 532 533**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 534 535| Name| Type | Mandatory| Description | 536| ---- | -------------------------------------- | ---- | ---------- | 537| text | [ResourceStr](ts-types.md#resourcestr) | Yes | Button text.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 538| accessibilityLevel<sup>13+</sup> | string | No | Accessibility level, which is used to set whether the current component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: The component can be recognized by accessibility services.<br>**"yes"**: The component can be recognized by accessibility services.<br>**"no"**: The component cannot be recognized by accessibility services.<br>**"no-hide-descendants"**: Neither the component nor its child components can be recognized by accessibility services.<br>Default value: **"auto"**<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 539| accessibilityDescription<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 540 541## SegmentButtonIconItem 542 543Provides icon button information. 544 545**System capability**: SystemCapability.ArkUI.ArkUI.Full 546 547**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 548 549|Name | Type | Mandatory| Description | 550| ------------ | -------------------------------------- | ---- | -------------------- | 551| icon | [ResourceStr](ts-types.md#resourcestr) | Yes | Icon of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 552| iconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 553| selectedIcon | [ResourceStr](ts-types.md#resourcestr) | Yes | Icon of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 554| selectedIconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 555| accessibilityLevel<sup>13+</sup> | string | No | Accessibility level, which is used to set whether the current component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: The component can be recognized by accessibility services.<br>**"yes"**: The component can be recognized by accessibility services.<br>**"no"**: The component cannot be recognized by accessibility services.<br>**"no-hide-descendants"**: Neither the component nor its child components can be recognized by accessibility services.<br>Default value: **"auto"**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 556| accessibilityDescription<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 557 558>**NOTE** 559> 560>For the settings to take effect, both **icon** and **selectedIcon** must be set. 561 562## SegmentButtonIconTextItem 563 564Provides icon+text button information. 565 566**System capability**: SystemCapability.ArkUI.ArkUI.Full 567 568**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 569 570### Properties 571 572| Name | Type | Mandatory| Description | 573| ------------ | -------------------------------------- | ---- | -------------------- | 574| icon | [ResourceStr](ts-types.md#resourcestr) | Yes | Icon of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 575| iconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 576| selectedIcon | [ResourceStr](ts-types.md#resourcestr) | Yes | Icon of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 577| selectedIconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 578| text | [ResourceStr](ts-types.md#resourcestr) | Yes | Button text.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 579| accessibilityLevel<sup>13+</sup> | string | No | Accessibility level, which is used to set whether the current component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: The component can be recognized by accessibility services.<br>**"yes"**: The component can be recognized by accessibility services.<br>**"no"**: The component cannot be recognized by accessibility services.<br>**"no-hide-descendants"**: Neither the component nor its child components can be recognized by accessibility services.<br>Default value: **"auto"**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 580| accessibilityDescription<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 581 582>**NOTE** 583> 584>For the settings to take effect, both **icon** and **selectedIcon** must be set. 585 586## SegmentButtonItemOptions 587 588Describes options of the items in the **SegmentButton** component. 589 590**Decorator Type**: @Observed 591 592**System capability**: SystemCapability.ArkUI.ArkUI.Full 593 594**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 595 596### Properties 597 598| Name | Type | Mandatory| Description | 599| ------------ | -------------------------------------- | ---- | -------------------- | 600| icon | [ResourceStr](ts-types.md#resourcestr) | No | Icon of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 601| iconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 602| selectedIcon | [ResourceStr](ts-types.md#resourcestr) | No | Icon of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 603| selectedIconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 604| text | [ResourceStr](ts-types.md#resourcestr) | No | Button text.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 605| accessibilityLevel<sup>13+</sup> | string | No | Accessibility level, which is used to set whether the current component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: The component can be recognized by accessibility services.<br>**"yes"**: The component can be recognized by accessibility services.<br>**"no"**: The component cannot be recognized by accessibility services.<br>**"no-hide-descendants"**: Neither the component nor its child components can be recognized by accessibility services.<br>Default value: **"auto"**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 606| accessibilityDescription<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 607 608### constructor 609 610constructor(options: SegmentButtonItemOptionsConstructorOptions) 611 612A constructor used to create a **SegmentButtonItemOptions** instance. 613 614**Atomic service API**: This API can be used in atomic services since API version 12. 615 616**System capability**: SystemCapability.ArkUI.ArkUI.Full 617 618**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 619 620**Parameters** 621 622 623| Name | Type | Mandatory| Description | 624| ------- | ------------------------------------------------------------ | ---- | ------------------ | 625| options | [SegmentButtonItemOptionsConstructorOptions](#segmentbuttonitemoptionsconstructoroptions) | Yes | Configuration options for a single segmented button, including the icon, text, and accessibility attributes.| 626 627## SegmentButtonItemOptionsConstructorOptions 628 629Describes the constructor parameters of **SegmentButtonItemOptions**. 630 631**System capability**: SystemCapability.ArkUI.ArkUI.Full 632 633**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 634 635### Properties 636 637| Name | Type | Mandatory| Description | 638| ------------ | -------------------------------------- | ---- | -------------------- | 639| icon | [ResourceStr](ts-types.md#resourcestr) | No | Icon of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 640| iconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the unselected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 641| selectedIcon | [ResourceStr](ts-types.md#resourcestr) | No | Icon of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 642| selectedIconAccessibilityText<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility text of the selected item.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 643| text | [ResourceStr](ts-types.md#resourcestr) | No | Button text.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 644| accessibilityLevel<sup>13+</sup> | string | No | Accessibility level, which is used to set whether the current component can be recognized by accessibility services.<br>The options are as follows:<br>**"auto"**: The component can be recognized by accessibility services.<br>**"yes"**: The component can be recognized by accessibility services.<br>**"no"**: The component cannot be recognized by accessibility services.<br>**"no-hide-descendants"**: Neither the component nor its child components can be recognized by accessibility services.<br>Default value: **"auto"**<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 645| accessibilityDescription<sup>13+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.<br>**Atomic service API**: This API can be used in atomic services since API version 13. | 646 647## Example 648 649### Example 1: Setting the Type of the SegmentButton component 650 651This example demonstrates how to create two different types of **SegmentButton** components by configuring **SegmentButtonOptions** with **tab** and **capsule** types. 652 653```ts 654// xxx.ets 655import { 656 ItemRestriction, 657 SegmentButton, 658 SegmentButtonItemTuple, 659 SegmentButtonOptions, 660 SegmentButtonTextItem 661} from '@kit.ArkUI'; 662 663@Entry 664@Component 665struct Index { 666 @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({ 667 buttons: [{ text: 'Tab 1' }, { text: 'Tab 2' }, { 668 text: 'Tab 3' 669 }] as ItemRestriction<SegmentButtonTextItem>, 670 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 671 }) 672 @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 673 buttons: [{ text: 'Single-select 1' }, { text: 'Single-select 2' }, { text: 'Single-select 3' }] as SegmentButtonItemTuple, 674 multiply: false, 675 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 676 }) 677 @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 678 buttons: [{ text: 'Multi-select 1' }, { text: 'Multi-select 2' }, { text: 'Multi-select 3' }] as SegmentButtonItemTuple, 679 multiply: true 680 }) 681 @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 682 buttons: [ 683 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 684 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 685 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 686 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') } 687 ] as SegmentButtonItemTuple, 688 multiply: false, 689 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 690 }) 691 @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 692 buttons: [ 693 { text: 'Icon 1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 694 { text: 'Icon 2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 695 { text: 'Icon 3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 696 { text: 'Icon 4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 697 { text: 'Icon 5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') } 698 ] as SegmentButtonItemTuple, 699 multiply: true 700 }) 701 @State tabSelectedIndexes: number[] = [1] 702 @State singleSelectCapsuleSelectedIndexes: number[] = [0] 703 @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1] 704 @State singleSelectIconCapsuleSelectedIndexes: number[] = [3] 705 @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2] 706 707 build() { 708 Row() { 709 Column() { 710 Column({ space: 25 }) { 711 SegmentButton({ options: this.tabOptions, 712 selectedIndexes: $tabSelectedIndexes }) 713 SegmentButton({ options: this.singleSelectCapsuleOptions, 714 selectedIndexes: $singleSelectCapsuleSelectedIndexes }) 715 SegmentButton({ 716 options: this.multiplySelectCapsuleOptions, 717 selectedIndexes: $multiplySelectCapsuleSelectedIndexes }) 718 SegmentButton({ options: this.iconCapsuleOptions, 719 selectedIndexes: $singleSelectIconCapsuleSelectedIndexes }) 720 SegmentButton({ options: this.iconTextCapsuleOptions, 721 selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes }) 722 }.width('90%') 723 }.width('100%') 724 }.height('100%') 725 } 726} 727``` 728 729 730 731### Example 2: Setting the Style of the SegmentButton component 732 733This example demonstrates how to use **CommonSegmentButtonOptions** to customize the text and background style of the **SegmentButton** component. 734 735```ts 736// xxx.ets 737import { 738 ItemRestriction, 739 SegmentButton, 740 SegmentButtonItemTuple, 741 SegmentButtonOptions, 742 SegmentButtonTextItem 743} from '@kit.ArkUI'; 744 745@Entry 746@Component 747struct Index { 748 @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({ 749 buttons: [{ text: 'Tab 1' }, { text: 'Tab 2' }, { 750 text: 'Tab 3' 751 }] as ItemRestriction<SegmentButtonTextItem>, 752 backgroundColor: 'rgb(213,213,213)', 753 selectedBackgroundColor: 'rgb(112,112,112)', 754 textPadding: { 755 top: 10, 756 right: 10, 757 bottom: 10, 758 left: 10 759 }, 760 }) 761 @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 762 buttons: [{ text: 'Single-select 1' }, { text: 'Single-select 2' }, { text: 'Single-select 3' }] as SegmentButtonItemTuple, 763 multiply: false, 764 fontColor: 'rgb(0,74,175)', 765 selectedFontColor: 'rgb(247,247,247)', 766 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 767 }) 768 @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 769 buttons: [{ text: 'Multi-select 1' }, { text: 'Multi-select 2' }, { text: 'Multi-select 3' }] as SegmentButtonItemTuple, 770 multiply: true, 771 fontSize: 18, 772 selectedFontSize: 18, 773 fontWeight: FontWeight.Bolder, 774 selectedFontWeight: FontWeight.Lighter, 775 }) 776 @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 777 buttons: [ 778 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 779 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 780 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 781 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') } 782 ] as SegmentButtonItemTuple, 783 multiply: false, 784 imageSize: { width: 40, height: 40 }, 785 buttonPadding: { 786 top: 6, 787 right: 10, 788 bottom: 6, 789 left: 10 790 }, 791 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 792 }) 793 @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 794 buttons: [ 795 { text: 'Icon 1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 796 { text: 'Icon 2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 797 { text: 'Icon 3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 798 { text: 'Icon 4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 799 { text: 'Icon 5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') } 800 ] as SegmentButtonItemTuple, 801 multiply: true, 802 imageSize: { width: 10, height: 10 }, 803 }) 804 @State tabSelectedIndexes: number[] = [0] 805 @State singleSelectCapsuleSelectedIndexes: number[] = [0] 806 @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1] 807 @State singleSelectIconCapsuleSelectedIndexes: number[] = [3] 808 @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2] 809 810 build() { 811 Row() { 812 Column() { 813 Column({ space: 20 }) { 814 SegmentButton({ options: this.tabOptions, selectedIndexes: $tabSelectedIndexes }) 815 SegmentButton({ 816 options: this.singleSelectCapsuleOptions, 817 selectedIndexes: $singleSelectCapsuleSelectedIndexes 818 }) 819 SegmentButton({ 820 options: this.multiplySelectCapsuleOptions, 821 selectedIndexes: $multiplySelectCapsuleSelectedIndexes 822 }) 823 SegmentButton({ 824 options: this.iconCapsuleOptions, 825 selectedIndexes: $singleSelectIconCapsuleSelectedIndexes 826 }) 827 SegmentButton({ 828 options: this.iconTextCapsuleOptions, 829 selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes 830 }) 831 }.width('90%') 832 }.width('100%') 833 }.height('100%') 834 } 835} 836``` 837 838 839 840### Example 3: Performing Array Operations on the SegmentButton Component 841 842This example shows how to perform operations such as adding and removing segmented buttons using array functions like **pop**, **shift**, and **unshift**. 843 844```ts 845import { 846 SegmentButton, 847 SegmentButtonOptions, 848 SegmentButtonItemOptionsArray, 849 SegmentButtonItemTuple, 850 SegmentButtonItemOptions 851} from '@kit.ArkUI'; 852 853@Entry 854@Component 855struct Index { 856 @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 857 buttons: [{ text: '1' }, { text: '2' }, { text: '3' }, 858 { text: '4' }, { text: '5' }] as SegmentButtonItemTuple, 859 multiply: false, 860 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 861 }) 862 @State capsuleSelectedIndexes: number[] = [0] 863 864 build() { 865 Row() { 866 Column() { 867 Column({ space: 10 }) { 868 SegmentButton({ 869 options: this.singleSelectCapsuleOptions, 870 selectedIndexes: $capsuleSelectedIndexes 871 }) 872 Button("Delete First Item") 873 .onClick(() => { 874 this.singleSelectCapsuleOptions.buttons.shift() 875 }) 876 Button("Delete Last Item") 877 .onClick(() => { 878 this.singleSelectCapsuleOptions.buttons.pop() 879 }) 880 Button("Add to End") 881 .onClick(() => { 882 this.singleSelectCapsuleOptions.buttons.push({ text: 'push' }) 883 }) 884 Button("Add to Beginning") 885 .onClick(() => { 886 this.singleSelectCapsuleOptions.buttons.unshift(({ text: 'unshift' })) 887 }) 888 Button("Replace Items 2 and 3 with splice1 and splice2") 889 .onClick(() => { 890 this.singleSelectCapsuleOptions.buttons.splice(1, 2, new SegmentButtonItemOptions({ 891 text: 'splice1' 892 }), new SegmentButtonItemOptions({ text: 'splice2' })) 893 }) 894 Button("Change All Button Text") 895 .onClick(() => { 896 this.singleSelectCapsuleOptions.buttons = 897 SegmentButtonItemOptionsArray.create([{ text: 'a' }, { text: 'b' }, 898 { text: 'c' }, { text: 'd' }, { text: 'e' }]) 899 }) 900 }.width('90%') 901 }.width('100%') 902 }.height('100%') 903 } 904} 905``` 906 907 908 909### Example 4: Implementing a Mirror Effect 910This example shows how to implement a mirror effect by configuring the **direction** property of the **SegmentButton** component. 911 912```ts 913// xxx.ets 914import { LengthMetrics, SegmentButton, SegmentButtonOptions } from '@kit.ArkUI'; 915 916 917@Entry 918@Component 919struct Index { 920 @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({ 921 buttons: [{ text: 'Tab 1' }, { text: 'Tab 2' }, { 922 text: 'Tab 3' 923 }], 924 direction: Direction.Rtl, 925 backgroundColor: Color.Green, 926 selectedBackgroundColor: Color.Orange, 927 localizedTextPadding: { 928 end: LengthMetrics.vp(10), 929 start: LengthMetrics.vp(10) 930 }, 931 }) 932 @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 933 buttons: [{ text: 'Single-select 1' }, { text: 'Single-select 2' }, { text: 'Single-select 3' }], 934 multiply: false, 935 direction: Direction.Rtl, 936 fontColor: Color.Black, 937 selectedFontColor: Color.Yellow, 938 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 939 }) 940 @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 941 buttons: [{ text: 'Multi-select 1' }, { text: 'Multi-select 2' }, { text: 'Multi-select 3' }], 942 multiply: true, 943 direction: Direction.Rtl, 944 fontSize: 18, 945 selectedFontSize: 18, 946 fontWeight: FontWeight.Bolder, 947 selectedFontWeight: FontWeight.Lighter, 948 }) 949 @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 950 buttons: [ 951 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 952 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 953 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 954 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 955 { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') } 956 ], 957 multiply: false, 958 direction: Direction.Rtl, 959 imageSize: { width: 40, height: 40 }, 960 localizedButtonPadding: { 961 end: LengthMetrics.vp(10), 962 start: LengthMetrics.vp(10) 963 }, 964 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 965 }) 966 @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 967 buttons: [ 968 { text: 'Icon 1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 969 { text: 'Icon 2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 970 { text: 'Icon 3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 971 { text: 'Icon 4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }, 972 { text: 'Icon 5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') } 973 ], 974 multiply: true, 975 direction: Direction.Rtl, 976 imageSize: { width: 10, height: 10 }, 977 }) 978 @State tabSelectedIndexes: number[] = [0] 979 @State singleSelectCapsuleSelectedIndexes: number[] = [0] 980 @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1] 981 @State singleSelectIconCapsuleSelectedIndexes: number[] = [3] 982 @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2] 983 984 build() { 985 Row() { 986 Column() { 987 Column({ space: 20 }) { 988 SegmentButton({ options: this.tabOptions, selectedIndexes: $tabSelectedIndexes }) 989 SegmentButton({ 990 options: this.singleSelectCapsuleOptions, 991 selectedIndexes: $singleSelectCapsuleSelectedIndexes 992 }) 993 SegmentButton({ 994 options: this.multiplySelectCapsuleOptions, 995 selectedIndexes: $multiplySelectCapsuleSelectedIndexes 996 }) 997 SegmentButton({ 998 options: this.iconCapsuleOptions, 999 selectedIndexes: $singleSelectIconCapsuleSelectedIndexes 1000 }) 1001 SegmentButton({ 1002 options: this.iconTextCapsuleOptions, 1003 selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes 1004 }) 1005 }.width('90%') 1006 }.width('100%') 1007 }.height('100%') 1008 } 1009} 1010``` 1011 1012 1013 1014### Example 5: Setting Accessibility 1015This example showcases how to implement accessibility features for the **SegmentButton** component by configuring properties such as **accessibilityLevel** and **selectedIconAccessibilityText**. 1016 1017```ts 1018// xxx.ets 1019import { 1020 ItemRestriction, 1021 SegmentButton, 1022 SegmentButtonItemTuple, 1023 SegmentButtonOptions, 1024 SegmentButtonTextItem, 1025 SegmentButtonItemOptions 1026} from '@kit.ArkUI'; 1027 1028@Entry 1029@Component 1030struct Index { 1031 @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({ 1032 buttons: [{ text: 'Tab 1', accessibilityLevel: 'yes', accessibilityDescription: 'Tab 1 usage hints' }, 1033 { text: 'Tab 2', accessibilityLevel: 'yes', accessibilityDescription: 'Tab 2 usage hints' }, 1034 { 1035 text: 'Tab 3 ', accessibilityLevel: 'yes', accessibilityDescription: 'Tab 3 usage hints' 1036 }] as ItemRestriction<SegmentButtonTextItem>, 1037 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 1038 }) 1039 @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 1040 buttons: [ 1041 { 1042 icon: $r('sys.media.ohos_ic_public_email'), 1043 iconAccessibilityText: 'Unselected icon accessibility text', 1044 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1045 selectedIconAccessibilityText: 'Selected icon accessibility text', 1046 accessibilityLevel: 'yes', 1047 accessibilityDescription: 'SegmentButtonIconItem usage hints' 1048 }, 1049 { 1050 icon: $r('sys.media.ohos_ic_public_email'), 1051 iconAccessibilityText: 'Unselected icon accessibility text', 1052 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1053 selectedIconAccessibilityText: 'Selected icon accessibility text', 1054 accessibilityLevel: 'yes', 1055 accessibilityDescription: 'SegmentButtonIconItem usage hints' 1056 }, 1057 { 1058 icon: $r('sys.media.ohos_ic_public_email'), 1059 iconAccessibilityText: 'Unselected icon accessibility text', 1060 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1061 selectedIconAccessibilityText: 'Selected icon accessibility text', 1062 accessibilityLevel: 'yes', 1063 accessibilityDescription: 'SegmentButtonIconItem usage hints' 1064 }, 1065 { 1066 icon: $r('sys.media.ohos_ic_public_email'), 1067 iconAccessibilityText: 'Unselected icon accessibility text', 1068 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1069 selectedIconAccessibilityText: 'Selected icon accessibility text', 1070 accessibilityLevel: 'yes', 1071 accessibilityDescription: 'SegmentButtonIconItem usage hints' 1072 } 1073 ] as SegmentButtonItemTuple, 1074 multiply: false, 1075 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK 1076 }) 1077 @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({ 1078 buttons: [ 1079 { 1080 text: 'Icon 1', 1081 icon: $r('sys.media.ohos_ic_public_email'), 1082 iconAccessibilityText: 'Unselected icon accessibility text', 1083 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1084 selectedIconAccessibilityText: 'Selected icon accessibility text', 1085 accessibilityLevel: 'yes', 1086 accessibilityDescription: 'SegmentButtonIconTextItem usage hints' 1087 }, 1088 { 1089 text: 'Icon 1', 1090 icon: $r('sys.media.ohos_ic_public_email'), 1091 iconAccessibilityText: 'Unselected icon accessibility text', 1092 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1093 selectedIconAccessibilityText: 'Selected icon accessibility text', 1094 accessibilityLevel: 'yes', 1095 accessibilityDescription: 'SegmentButtonIconTextItem usage hints' 1096 }, 1097 { 1098 text: 'Icon 1', 1099 icon: $r('sys.media.ohos_ic_public_email'), 1100 iconAccessibilityText: 'Unselected icon accessibility text', 1101 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1102 selectedIconAccessibilityText: 'Selected icon accessibility text', 1103 accessibilityLevel: 'yes', 1104 accessibilityDescription: 'SegmentButtonIconTextItem usage hints' 1105 }, 1106 { 1107 text: 'Icon 1', 1108 icon: $r('sys.media.ohos_ic_public_email'), 1109 iconAccessibilityText: 'Unselected icon accessibility text', 1110 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1111 selectedIconAccessibilityText: 'Selected icon accessibility text', 1112 accessibilityLevel: 'yes', 1113 accessibilityDescription: 'SegmentButtonIconTextItem usage hints' 1114 } 1115 ] as SegmentButtonItemTuple, 1116 multiply: true 1117 }) 1118 @State tabSelectedIndexes: number[] = [1] 1119 @State singleSelectIconCapsuleSelectedIndexes: number[] = [3] 1120 @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2] 1121 1122 build() { 1123 Row() { 1124 Column() { 1125 Column({ space: 25 }) { 1126 SegmentButton({ 1127 options: this.tabOptions, 1128 selectedIndexes: $tabSelectedIndexes 1129 }) 1130 SegmentButton({ 1131 options: this.iconCapsuleOptions, 1132 selectedIndexes: $singleSelectIconCapsuleSelectedIndexes 1133 }) 1134 SegmentButton({ 1135 options: this.iconTextCapsuleOptions, 1136 selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes 1137 }) 1138 Button("Replace Items 2 and 3 with splice1 and splice2") 1139 .onClick(() => { 1140 this.iconTextCapsuleOptions.buttons.splice(1, 2, new SegmentButtonItemOptions({ 1141 text: 'splice1', accessibilityLevel: 'yes', accessibilityDescription: 'SegmentButtonItemOptions usage hints' 1142 }), new SegmentButtonItemOptions({ 1143 text: 'splice2', 1144 icon: $r('sys.media.ohos_ic_public_email'), 1145 iconAccessibilityText: 'Unselected icon accessibility text', 1146 selectedIcon: $r('sys.media.ohos_ic_public_clock'), 1147 selectedIconAccessibilityText: 'Selected icon accessibility text', 1148 accessibilityLevel: 'yes', 1149 accessibilityDescription: 'SegmentButtonIconTextItem usage hints' 1150 })) 1151 }) 1152 }.width('90%') 1153 }.width('100%') 1154 }.height('100%') 1155 } 1156} 1157``` 1158 1159### Example 6: Setting Custom Border Radius 1160 1161This example demonstrates how to set a custom border radius for the **SegmentButton** component. 1162 1163```ts 1164// xxx.ets 1165import { 1166 BorderRadiusMode, 1167 ItemRestriction, 1168 LengthMetrics, 1169 SegmentButton, 1170 SegmentButtonOptions, 1171 SegmentButtonTextItem 1172} from '@kit.ArkUI'; 1173 1174@Entry 1175@Component 1176struct Index { 1177 @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({ 1178 buttons: [{ text: 'Tab 1' }, { text: 'Tab 2' }, { 1179 text: 'Tab 3' 1180 }] as ItemRestriction<SegmentButtonTextItem>, 1181 backgroundBlurStyle: BlurStyle.BACKGROUND_THICK, 1182 borderRadiusMode: BorderRadiusMode.CUSTOM, 1183 backgroundBorderRadius: LengthMetrics.vp(8), 1184 itemBorderRadius: LengthMetrics.vp(6) 1185 }) 1186 @State tabSelectedIndexes: number[] = [1] 1187 1188 build() { 1189 Row() { 1190 Column() { 1191 Column({ space: 25 }) { 1192 SegmentButton({ 1193 options: this.tabOptions, 1194 selectedIndexes: $tabSelectedIndexes, 1195 }) 1196 }.width('90%') 1197 }.width('100%') 1198 }.height('100%') 1199 } 1200} 1201``` 1202 1203 1204
