@ohos.arkui.advanced.SegmentButton (Segment Button)

A segment button is a group of options, such as tabs, single-select options, and multi-select options.

NOTE

This component and its child components are supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { SegmentButton, SegmentButtonOptions, SegmentButtonItemOptionsArray } from '@ohos.arkui.advanced.SegmentButton'

Child Components

Not supported

SegmentButton

SegmentButton({ options: SegmentButtonOptions, selectedIndexes: number[] })

Decorator: @Component

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

The segment button does not support the universal attributes. The segment button takes up the maximum width allowed by the content area, and evenly allocates the width among its options. It adapts its height automatically to the content (text and image), the minimum height being 28 vp.

SegmentButtonOptions

Provides initial data and custom attributes for the segment button.

Attributes

constructor

constructor(options: TabSegmentButtonOptions | CapsuleSegmentButtonOptions)

Implements a constructor.

Parameters

tab

static tab(options: TabSegmentButtonConstructionOptions): SegmentButtonOptions

Creates a SegmentButtonOptions object for the segment button consisting of tabs.

Parameters

Return value

capsule

static capsule(options: CapsuleSegmentButtonConstructionOptions): SegmentButtonOptions

Creates a SegmentButtonOptions object for the segment button consisting of single-select or multi-select options.

Parameters

Return value

DimensionNoPercentage

Represents the length union type that does not support values in percentage.

System capability: SystemCapability.ArkUI.ArkUI.Full

CommonSegmentButtonOptions

Defines the attributes that can be customized for the segment button.

System capability: SystemCapability.ArkUI.ArkUI.Full

Attributes

TabSegmentButtonConstructionOptions

Implements a SegmentButtonOptions object for the segment button consisting of tabs.

It inherits CommonSegmentButtonOptions.

System capability: SystemCapability.ArkUI.ArkUI.Full

CapsuleSegmentButtonConstructionOptions

Implements a SegmentButtonOptions object for the segment button consisting of single-select or multi-select options.

It inherits CommonSegmentButtonOptions.

System capability: SystemCapability.ArkUI.ArkUI.Full

ItemRestriction

Represents a tuple used to store button information.

NOTE

A segment button supports two to five options.

SegmentButtonItemTuple

Represents the tuple union type used to store button information.

System capability: SystemCapability.ArkUI.ArkUI.Full

SegmentButtonItemArray

Represents the array union type used to store button information.

System capability: SystemCapability.ArkUI.ArkUI.Full

SegmentButtonItemOptionsArray

Implements an array for storing button information.

NOTE

A segment button supports two to five options. As such, a SegmentButtonItemOptionsArray object stores information about only two to five button options.

constructor

constructor(elements: SegmentButtonItemTuple)

Implements a constructor.

Parameters

push

push(...items: SegmentButtonItemArray): number

Adds the specified elements to the end of this array and returns the new length of the array.

Parameters

Return value

NOTE

A segment button supports two to five options. As such, a SegmentButtonItemOptionsArray object stores information about only two to five button options. If the number limit is reached, this API will not work.

pop

pop(): SegmentButtonItemOptions | undefined

Removes the last element from this array and returns that element.

Return value

NOTE

A segment button supports two to five options. As such, a SegmentButtonItemOptionsArray object stores information about only two to five button options. If the number limit is reached, this API will not work.

shift

shift(): SegmentButtonItemOptions | undefined

Removes the first element from this array and returns that element.

Return value

NOTE

A segment button supports two to five options. As such, a SegmentButtonItemOptionsArray object stores information about only two to five button options. If the number limit is reached, this API will not work.

unshift

unshift(...items: SegmentButtonItemArray): number

Adds the specified elements to the beginning of this array and returns the new length of the array.

Parameters

Return value

NOTE

A segment button supports two to five options. As such, a SegmentButtonItemOptionsArray object stores information about only two to five button options. If the number limit is reached, this API will not work.

splice

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

Changes 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.

Parameters

Return value

NOTE

A segment button supports two to five options. As such, a SegmentButtonItemOptionsArray object stores information about only two to five button options. If the number limit is reached, this API will not work.

create

static create(elements: SegmentButtonItemTuple): SegmentButtonItemOptionsArray

Creates a SegmentButtonItemOptionsArray object.

Parameters

Return value

TabSegmentButtonOptions

Provides the options of the segment button consisting of tabs. It inherits TabSegmentButtonConstructionOptions.

System capability: SystemCapability.ArkUI.ArkUI.Full

CapsuleSegmentButtonOptions

Provides the options of the segment button consisting of single-select or multi-select options. It inherits CapsuleSegmentButtonConstructionOptions.

System capability: SystemCapability.ArkUI.ArkUI.Full

SegmentButtonTextItem

Provides text button information.

System capability: SystemCapability.ArkUI.ArkUI.Full

SegmentButtonIconItem

Provides icon button information.

System capability: SystemCapability.ArkUI.ArkUI.Full

NOTE

For the settings to take effect, both icon and selectedIcon must be set.

SegmentButtonIconTextItem

Provides icon+text button information.

System capability: SystemCapability.ArkUI.ArkUI.Full

NOTE

For the settings to take effect, both icon and selectedIcon must be set.

SegmentButtonItemOptions

Describes options of the segment button.

Attributes

constructor

constructor(options: SegmentButtonItemOptionsConstructorOptions)

Implements a constructor.

Parameters

SegmentButtonItemOptionsConstructorOptions

Describes the constructor parameters of SegmentButtonItemOptions.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

Example 1

// xxx.ets
import {
  ItemRestriction,
  SegmentButton,
  SegmentButtonItemTuple,
  SegmentButtonOptions,
  SegmentButtonTextItem
} from '@ohos.arkui.advanced.SegmentButton'

@Entry
@Component
struct Index {
  @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
    buttons: [{ text: 'Tab 1' }, { text: 'Tab 2' }, {
      text: 'Tab 3'
    }] as ItemRestriction<SegmentButtonTextItem>,
    backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  })
  @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [{ text: 'Single-select 1' }, { text: 'Single-select 2' }, { text: 'Single-select 3' }] as SegmentButtonItemTuple,
    multiply: false,
    backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  })
  @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [{ text: 'Multi-select 1' }, { text: 'Multi-select 2' }, { text: 'Multi-select 3' }] as SegmentButtonItemTuple,
    multiply: true
  })
  @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
    ] as SegmentButtonItemTuple,
    multiply: false,
    backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  })
  @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [
      { text: 'Icon 1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
    ] as SegmentButtonItemTuple,
    multiply: true
  })
  @State tabSelectedIndexes: number[] = [1]
  @State singleSelectCapsuleSelectedIndexes: number[] = [0]
  @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1]
  @State singleSelectIconCapsuleSelectedIndexes: number[] = [3]
  @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2]

  build() {
    Row() {
      Column() {
        Column({ space: 25 }) {
          SegmentButton({ options: this.tabOptions,
            selectedIndexes: $tabSelectedIndexes })
          SegmentButton({ options: this.singleSelectCapsuleOptions,
            selectedIndexes: $singleSelectCapsuleSelectedIndexes })
          SegmentButton({
            options: this.multiplySelectCapsuleOptions,
            selectedIndexes: $multiplySelectCapsuleSelectedIndexes })
          SegmentButton({ options: this.iconCapsuleOptions,
            selectedIndexes: $singleSelectIconCapsuleSelectedIndexes })
          SegmentButton({ options: this.iconTextCapsuleOptions,
            selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes })
        }.width('90%')
      }.width('100%')
    }.height('100%')
  }
}

Example 2

// xxx.ets
import {
  ItemRestriction,
  SegmentButton,
  SegmentButtonItemTuple,
  SegmentButtonOptions,
  SegmentButtonTextItem
} from '@ohos.arkui.advanced.SegmentButton'

@Entry
@Component
struct Index {
  @State tabOptions: SegmentButtonOptions = SegmentButtonOptions.tab({
    buttons: [{ text: 'Tab 1' }, { text: 'Tab 2' }, {
      text: 'Tab 3'
    }] as ItemRestriction<SegmentButtonTextItem>,
    backgroundColor: Color.Green,
    selectedBackgroundColor: Color.Orange,
    textPadding: { top: 10, right: 10, bottom: 10, left: 10 },
  })
  @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [{ text: 'Single-select 1' }, { text: 'Single-select 2' }, { text: 'Single-select 3' }] as SegmentButtonItemTuple,
    multiply: false,
    fontColor: Color.Black,
    selectedFontColor: Color.Yellow,
    backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  })
  @State multiplySelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [{ text: 'Multi-select 1' }, { text: 'Multi-select 2' }, { text: 'Multi-select 3' }] as SegmentButtonItemTuple,
    multiply: true,
    fontSize: 18,
    selectedFontSize: 18,
    fontWeight: FontWeight.Bolder,
    selectedFontWeight: FontWeight.Lighter,
  })
  @State iconCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
    ] as SegmentButtonItemTuple,
    multiply: false,
    imageSize: { width: 40, height: 40 },
    buttonPadding: { top: 6, right: 10, bottom: 6, left: 10 },
    backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  })
  @State iconTextCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [
      { text: 'Icon 1', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 2', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 3', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 4', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') },
      { text: 'Icon 5', icon: $r('sys.media.ohos_ic_public_email'), selectedIcon: $r('sys.media.ohos_ic_public_clock') }
    ] as SegmentButtonItemTuple,
    multiply: true,
    imageSize: { width: 10, height: 10 },
  })
  @State tabSelectedIndexes: number[] = [0]
  @State singleSelectCapsuleSelectedIndexes: number[] = [0]
  @State multiplySelectCapsuleSelectedIndexes: number[] = [0, 1]
  @State singleSelectIconCapsuleSelectedIndexes: number[] = [3]
  @State multiplySelectIconTextCapsuleSelectedIndexes: number[] = [1, 2]

  build() {
    Row() {
      Column() {
        Column({ space: 20 }) {
          SegmentButton({ options: this.tabOptions, selectedIndexes: $tabSelectedIndexes })
          SegmentButton({ options: this.singleSelectCapsuleOptions,
            selectedIndexes: $singleSelectCapsuleSelectedIndexes })
          SegmentButton({ options: this.multiplySelectCapsuleOptions,
            selectedIndexes: $multiplySelectCapsuleSelectedIndexes })
          SegmentButton({ options: this.iconCapsuleOptions,
            selectedIndexes: $singleSelectIconCapsuleSelectedIndexes })
          SegmentButton({ options: this.iconTextCapsuleOptions,
            selectedIndexes: $multiplySelectIconTextCapsuleSelectedIndexes })
        }.width('90%')
      }.width('100%')
    }.height('100%')
  }
}

Example 3

import {
  SegmentButton,
  SegmentButtonOptions,
  SegmentButtonItemOptionsArray,
  SegmentButtonItemTuple,
  SegmentButtonItemOptions
} from '@ohos.arkui.advanced.SegmentButton'

@Entry
@Component
struct Index {
  @State singleSelectCapsuleOptions: SegmentButtonOptions = SegmentButtonOptions.capsule({
    buttons: [{ text: '1' }, { text: '2' }, { text: '3' },
      { text: '4' }, { text: '5' }] as SegmentButtonItemTuple,
    multiply: false,
    backgroundBlurStyle: BlurStyle.BACKGROUND_THICK
  })
  @State capsuleSelectedIndexes: number[] = [0]

  build() {
    Row() {
      Column() {
        Column({ space: 10 }) {
          SegmentButton({ options: this.singleSelectCapsuleOptions,
            selectedIndexes: $capsuleSelectedIndexes })
          Button ("Delete First Option")
            .onClick(() => {
              this.singleSelectCapsuleOptions.buttons.shift()
            })
          Button ("Delete Last Option")
            .onClick(() => {
              this.singleSelectCapsuleOptions.buttons.pop()
            })
          Button ("Add push to End")
            .onClick(() => {
              this.singleSelectCapsuleOptions.buttons.push({ text: 'push' })
            })
          Button ("Add unshift to Beginning")
            .onClick(() => {
              this.singleSelectCapsuleOptions.buttons.unshift(({ text: 'unshift' }))
            })
          Button ("Replace Options 2 and 3 with splice1 and splice2")
            .onClick(() => {
              this.singleSelectCapsuleOptions.buttons.splice(1, 2, new SegmentButtonItemOptions({
                text: 'splice1'
              }), new SegmentButtonItemOptions({ text: 'splice2' }))
            })
          Button ("Change All Button Text")
            .onClick(() => {
              this.singleSelectCapsuleOptions.buttons =
              SegmentButtonItemOptionsArray.create([{ text: 'a' }, { text: 'b' },
                { text: 'c' }, { text: 'd' }, { text: 'e' }])
            })
        }.width('90%')
      }.width('100%')
    }.height('100%')
  }
}