HarmonyOS 6 TabSegmentButtonV2 页签型分段按钮使用文档

模块导入

import { SegmentButtonV2Items, TabSegmentButtonV2 } from '@kit.ArkUI';

核心API说明

1. 组件必填参数

2. 选项对象类型

• 纯文本：{text: '文字'}
• 图片图标：{icon: 系统资源}
• 符号图标：{symbol: 系统符号资源}
• 图文混合：同时配置text+icon/symbol

3. 内置判断接口

• item.isHybrid：单个选项是否图文混合
• items.hasHybrid：整组按钮是否存在混合选项

完整代码

import { SegmentButtonV2Items, TabSegmentButtonV2 } from '@kit.ArkUI'; @Entry @ComponentV2 struct TabSegmentButtonV2Example { // 1.纯文本选项 @Local textItems: SegmentButtonV2Items = new SegmentButtonV2Items([ { text: '手机' },{ text: '平板' },{ text: '2in1' },{ text: '智能穿戴' }, ]); @Local textSelectedIndex: number = 0; // 2.图片图标选项 @Local imageItems: SegmentButtonV2Items = new SegmentButtonV2Items([ { icon: $r('sys.media.ohos_ic_public_device_phone') }, { icon: $r('sys.media.ohos_ic_public_device_pad') }, { icon: $r('sys.media.ohos_ic_public_device_matebook') }, { icon: $r('sys.media.ohos_ic_public_device_watch') }, ]); @Local imageSelectedIndex: number = 0; // 3.系统符号图标选项 @Local symbolItems: SegmentButtonV2Items = new SegmentButtonV2Items([ { symbol: $r('sys.symbol.phone') }, { symbol: $r('sys.symbol.pad') }, { symbol: $r('sys.symbol.matebook') }, { symbol: $r('sys.symbol.watch') }, ]); @Local symbolSelectedIndex: number = 0; // 4.图文混合选项 @Local hybridItems: SegmentButtonV2Items = new SegmentButtonV2Items([ { text: '手机', symbol: $r('sys.symbol.phone') }, { text: '平板', symbol: $r('sys.symbol.pad') }, { text: '2in1', symbol: $r('sys.symbol.matebook') }, { text: '智能穿戴', symbol: $r('sys.symbol.watch') }, ]); @Local hybridSelectedIndex: number = 0; // 5.自由混搭不规则选项 @Local freeItems: SegmentButtonV2Items = new SegmentButtonV2Items([ { text: '年' },{ text: '月' },{ text: '周' },{ text: '日' }, { icon: $r('sys.media.ohos_ic_public_search_filled') }, ]); @Local freeSelectedIndex: number = 0; build() { Scroll() { Column({ space: 12 }) { VCard({ title: '纯文本选项' }) { TabSegmentButtonV2({ items: this.textItems, selectedIndex: this.textSelectedIndex, }) } VCard({ title: '纯图片图标选项' }) { TabSegmentButtonV2({ items: this.imageItems, selectedIndex: this.imageSelectedIndex, }) } VCard({ title: '纯符号图标选项' }) { TabSegmentButtonV2({ items: this.symbolItems, selectedIndex: this.symbolSelectedIndex, }) } VCard({ title: '图文混合选项' }) { TabSegmentButtonV2({ items: this.hybridItems, selectedIndex: this.hybridSelectedIndex, }) } VCard({ title: '自由混搭选项' }) { TabSegmentButtonV2({ items: this.freeItems, selectedIndex: this.freeSelectedIndex, }) } // 混合属性判断演示 Button(`单项是否图文混合：${this.textItems[0].isHybrid}`).width('70%') Button(`单项是否图文混合：${this.hybridItems[0].isHybrid}`).width('70%') Button(`整组是否含混合项：${this.textItems.hasHybrid}`).width('70%') Button(`整组是否含混合项：${this.hybridItems.hasHybrid}`).width('70%') } .padding(16) } .backgroundColor('#f1f3f5') .width('100%') .height('100%') } } // 卡片封装组件 @Builder function Noop() {} @Component export struct VCard { @Prop title: ResourceStr; @BuilderParam content: () => void = Noop; build() { Column({ space: 8 }) { Text(this.title) .maxLines(1) .textOverflow({ overflow: TextOverflow.Ellipsis }) this.content() } .backgroundColor(Color.White) .borderRadius(8) .padding(8) .width('100%') } }

运行效果如图：

代码逻辑解析

1. 状态声明
   使用@Local定义V2局部状态，分别存储5种不同风格的按钮数据集与选中下标。

2. 数据实例化
   通过new SegmentButtonV2Items([])批量创建选项数组，支持多种元素随意组合。

3. 页签组件挂载
   固定传入items数据集与selectedIndex选中下标，自动渲染页签样式按钮，点击自动切换选中状态。

4. 混合属性判定

• isHybrid：判断单个选项是否同时存在文字与图标
• hasHybrid：批量判断整组按钮有无混合样式条目

总结

1. 仅API 18及以上可用，低版本无法编译运行
2. 必须搭配@ComponentV2装饰器，不兼容旧式@Component写法
3. 手表设备暂不支持该组件，手机、平板、PC设备正常使用
4. 选项支持任意混搭，无需统一同一种样式

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力