HarmonyOS6 Tabs 组件完全指南：从零上手底部导航

一、Tabs 组件是什么？

Tabs 是 HarmonyOS ArkUI 框架内置的标签页导航组件，几乎所有主流应用的底部导航栏都由它来承载。它把多个内容页面叠放在一起，通过点击顶部或底部的标签按钮来切换视图。

生活中有一个非常直观的类比：就像一本有分隔页的活页笔记本，每个分隔页标有不同的分类名称。Tabs 组件就是这本笔记本在应用里的数字形态。

二、核心结构

Tabs 组件由两部分协作完成导航：

• TabBar：标签导航栏，可出现在顶部、底部或侧边。
• TabContent：内容区，是 Tabs 的唯一合法直接子组件，每个TabContent对应一个标签页面。

三、基础接口说明

// Tabs 构造参数Tabs({barPosition?:BarPosition,// 标签栏位置，Start（顶部）或 End（底部）index?:number,// 初始选中索引，默认 0controller?:TabsController// 编程控制器，可在代码中主动切换标签})

barPosition与vertical属性组合，决定标签栏最终出现的位置：

四、基础用法示例

4.1 最简单的底部标签栏

@Entry@Componentstruct BasicTabsDemo{build(){// barPosition.End 将标签栏放在屏幕底部Tabs({barPosition:BarPosition.End}){TabContent(){Text('首页内容')}.tabBar('首页')// 字符串形式设置标签文字TabContent(){Text('分类内容')}.tabBar('分类')TabContent(){Text('我的内容')}.tabBar('我的')}}}

代码说明：

• barPosition: BarPosition.End让标签栏出现在底部；
• .tabBar('文字')是最简单的标签设置方式，系统会渲染默认样式；
• 每个TabContent内部可以放任意组件，包括List、Grid、Scroll等。

4.2 带系统图标的标签栏

TabContent(){Text('首页内容')}.tabBar({icon:$r('sys.symbol.house'),// 未选中时显示的图标activeIcon:$r('sys.symbol.house_fill'),// 选中时显示的图标text:'首页'})

代码说明：

• $r('sys.symbol.house')引用 HarmonyOS 内置的 Symbol 图标，不需要导入额外图片资源；
• sys.symbol.xxx_fill是填充版图标，视觉上更突出，适合选中状态。

4.3 完全自定义标签（推荐方式）

在本项目的RegularTabsDemo.ets中，自定义标签栏的核心实现如下：

// 标签数据由 TabItem 接口统一管理@Statetabs:TabItem[]=[];// 在 aboutToAppear 中初始化数据aboutToAppear(){this.tabs=[{id:'home',icon:$r('sys.symbol.house'),activeIcon:$r('sys.symbol.house_fill'),title:'首页',},{id:'cart',icon:$r('sys.symbol.cart'),activeIcon:$r('sys.symbol.cart_fill'),title:'购物车',badge:3,// 角标数量},// ...];}// 自定义 TabBar UIRow(){ForEach(this.tabs,(tab:TabItem,index:number)=>{Column(){// 根据 currentIndex 切换图标和颜色SymbolGlyph(this.currentIndex===index?tab.activeIcon:tab.icon).fontSize(24).fontColor(this.currentIndex===index?['#007AFF']:['#8E8E93'])Text(tab.title).fontSize(11).fontColor(this.currentIndex===index?'#007AFF':'#8E8E93').margin({top:2})}.width(60).height(56).justifyContent(FlexAlign.Center).onClick(()=>{this.currentIndex=index;// 点击时更新状态})})}

代码说明：

• @State currentIndex作为选中状态的唯一数据源，它变化时 UI 自动刷新；
• SymbolGlyph的.fontColor()接受的是ResourceColor[]数组，所以要写成['#007AFF']而非直接写字符串；
• ForEach遍历tabs数组动态生成每一个标签项，增减标签只需修改数据，UI 自动跟随变化。

五、重要属性一览

5.1 barMode — 标签栏排列模式

Tabs().barMode(BarMode.Fixed)// 固定：标签等宽平铺，适合 3-5 个标签Tabs().barMode(BarMode.Scrollable)// 可滚动：标签可横向滑动，适合 5 个以上

5.2 scrollable — 是否允许手势滑动切换

Tabs().scrollable(true)// 允许左右滑动切换内容（默认开启）Tabs().scrollable(false)// 禁止滑动，只能点击标签切换

注意：如果你实现了完全自定义的 TabBar，通常需要把scrollable设为false，避免手势滑动与自定义逻辑冲突。

5.3 animationDuration — 切换动画时长

Tabs().animationDuration(300)// 切换页面时的动画时长，单位毫秒Tabs().animationDuration(0)// 设为 0 则关闭切换动画

5.4 barHeight — 标签栏高度

Tabs().barHeight(60)// 标签栏高度，单位 vp.barWidth('80%')// 纵向标签栏时有效，控制侧边栏宽度

六、onChange — 监听切换事件

Tabs().onChange((index:number)=>{// index 是用户切换后的目标标签索引this.currentIndex=index;console.log(`当前标签:${index}`);})

代码说明：

• 不管是用户点击还是手势滑动，切换完成后都会触发onChange；
• 如果使用了TabsController.changeIndex()主动切换，onChange同样会被触发，要注意避免循环调用。

七、隐藏系统标签栏（完全自定义场景）

当需要实现浮动标签栏、舵式标签栏等自定义外观时，需要先把系统默认的 TabBar 隐藏掉：

Tabs({barPosition:BarPosition.End,index:this.currentIndex}){ForEach(this.tabs,(tab:TabItem)=>{TabContent(){// 内容页面}// 注意：不调用 .tabBar()，或者配合 .barHeight(0) 隐藏})}.barHeight(0)// 将系统 TabBar 高度设为 0，视觉上完全隐藏.barOverlap(false)// 不让 TabBar 与内容重叠

然后在外层单独绘制自定义的 TabBar 组件。

八、常见问题

Q1：TabContent 里可以放 List 吗？

可以放任意组件：

TabContent(){List(){ListItem(){Text('项目1')}ListItem(){Text('项目2')}}}.tabBar('列表')

Q2：如何避让系统底部导航条？

// 在自定义 TabBar 上添加此属性，自动扩展至安全区域Row().expandSafeArea([SafeAreaType.SYSTEM],[SafeAreaEdge.BOTTOM])

Q3：如何在代码中跳转到指定标签？

使用TabsController，见下一篇文章的详细讲解。

总结

Tabs 组件是 HarmonyOS 应用里使用频率最高的导航结构之一，入门门槛并不高。掌握barPosition、barMode、onChange这几个核心属性，就能应对绝大多数日常场景。当系统默认样式满足不了设计需求时，把barHeight设为 0 再自己绘制 TabBar，能拿到完整的 UI 控制权。真正有意思的部分，恰恰从"自定义"开始——接下来几篇文章会带你一步步把这件事做得更漂亮。