对应Demo: TabViewDemo | 难度: 中级 | 关键词: Tabs, TabsController, BarMode, 自定义tabBar, SymbolGlyph

几乎所有App的首页都是底部导航栏+多个Tab页的组合，HarmonyOS NEXT用Tabs组件来实现这个需求。文档上看着简单——Tabs里放几个TabContent，设个barPosition到底部就完事了。但真正做项目的时候你会发现：自定义tabBar的选中态不会自动同步、onChange在初始化时就触发一次、6个以上Tab用Fixed模式文字被截断、TabContent默认全部预加载浪费内存……这篇把Tabs组件从基础用法到深度定制的完整链路走一遍，顺带对比Swiper和Navigation的适用场景。

请添加图片描述

Tabs的基本结构：TabsController是关键

TabViewDemo的核心结构：

@State innerTabIndex: number = 0;
private innerController: TabsController = new TabsController();

Tabs({ controller: this.innerController }) {
  TabContent() {
    this.tabPageContent('首页', '首页内容区域', 0)
  }.tabBar(this.customTabBuilder(0, '首页', $r('sys.symbol.house')))

  TabContent() {
    this.tabPageContent('搜索', '搜索功能区域', 1)
  }.tabBar(this.customTabBuilder(1, '搜索', $r('sys.symbol.magnifyingglass')))

  TabContent() {
    this.tabPageContent('收藏', '收藏内容区域', 2)
  }.tabBar(this.customTabBuilder(2, '收藏', $r('sys.symbol.heart')))

  TabContent() {
    this.tabPageContent('我的', '个人中心区域', 3)
  }.tabBar(this.customTabBuilder(3, '我的', $r('sys.symbol.person')))
}
.barMode(this.isScrollableMode ? BarMode.Scrollable : BarMode.Fixed)
.barPosition(BarPosition.End)
.onChange((index: number) => {
  let numIndex: number = Number(index);
  this.innerTabIndex = numIndex;
  this.onChangeLog = 'Tab切换->' + numIndex.toString();
})

TabsController的作用是程序化切换Tab。你调this.innerController.changeIndex(2)就能跳到第三个Tab，不需要用户手动点。这在很多场景下很实用——比如推送通知跳转到消息Tab、深链接直接打开搜索页。

Tabs构造函数还支持{ index: this.innerTabIndex }的方式传入初始索引，但要注意：这个index只在组件首次创建时生效，后续你改innerTabIndex不会自动切换Tab。想程序化切换必须用TabsController.changeIndex()。

barPosition设成BarPosition.End把tabBar放到底部，这是App首页的标准布局。BarPosition.Start是顶部tabBar，适合内容分类页（类似今日头条顶部的"推荐/热榜/视频"切换）。

BarMode.Fixed vs BarMode.Scrollable：5个Tab是个分界线

TabViewDemo里有个开关可以在两种模式间切换：

@State isScrollableMode: boolean = false;

Toggle({ type: ToggleType.Switch, isOn: this.isScrollableMode })
  .onChange((isOn: boolean) => {
    this.isScrollableMode = isOn;
  })

// Tabs上
.barMode(this.isScrollableMode ? BarMode.Scrollable : BarMode.Fixed)

BarMode.Fixed：所有Tab均分tabBar宽度。4个Tab每个占25%，5个每个占20%，6个就开始挤了——文字被截断，图标缩小，用户体验直线下降。Fixed模式适用于Tab数量不超过5个的场景。

BarMode.Scrollable：Tab按自身内容宽度排列，放不下时可以横向滑动。每个Tab的宽度由内容决定，不会强行均分。适合6个以上Tab的场景，但用户需要滑动才能看到后面的Tab，可发现性较差。

我做过一个项目，产品非要放6个Tab用Fixed模式，结果"设置"两个字变成了"设…"。最后说服产品把"设置"改成齿轮图标+单字"设"才勉强塞下。所以从一开始就和产品确认Tab数量——超过5个，要么合并功能，要么上Scrollable模式。

还有一个细节：Scrollable模式下，点击一个不可见的Tab时，tabBar会自动滚动到那个Tab的位置，但这个滚动没有动画过渡，是瞬移的，体验不太好。如果对体验要求高，可能需要自己实现tabBar。

自定义tabBar：选中态手动同步是最大坑

TabViewDemo的自定义tabBar用了@Builder + SymbolGlyph：

@Builder
customTabBuilder(index: number, name: string, icon: Resource) {
  Column() {
    SymbolGlyph(icon)
      .fontColor([this.innerTabIndex === index ? '#007DFF' : '#999999'])
      .fontSize(22)
    Text(name)
      .fontSize(10)
      .fontColor(this.innerTabIndex === index ? '#007DFF' : '#999999')
      .margin({ top: 2 })
  }
  .justifyContent(FlexAlign.Center)
  .height(56)
  .width('100%')
}

关键点：this.innerTabIndex === index 这个判断。自定义tabBar不会自动管理选中态——你必须自己在onChange回调里更新innerTabIndex，然后在builder里用这个值判断颜色。

如果你忘了在onChange里更新innerTabIndex，或者忘了在builder里用这个值做条件判断，就会出现：点击Tab切换了内容，但tabBar上的选中态还停在原来的位置。

onChange的完整逻辑：

.onChange((index: number) => {
  let numIndex: number = Number(index);
  this.innerTabIndex = numIndex;
  this.onChangeLog = 'Tab切换->' + numIndex.toString();
  hilog.info(DOMAIN, TAG, 'Inner tab onChange: ' + numIndex.toString());
})

这里用Number(index)做了显式转换。虽然onChange的index参数类型是number，但在某些边界情况下（比如通过TabsController.changeIndex传入），index的实际值可能是其他类型，Number()确保得到安全的number值。

SymbolGlyph用了系统符号图标$r('sys.symbol.house')。HarmonyOS NEXT内置了大量系统符号（sys.symbol.*），可以直接引用，不需要自己切图。这是比Android和iOS方便的地方——类似于SF Symbols，但需要查官方文档找对应的符号名。

请添加图片描述

onChange在初始化时触发：第一个坑

TabViewDemo的对比指南里明确指出了这一点：

Tabs组件初始化时会触发一次onChange回调，index为0，需在业务逻辑中区分初始化触发和用户切换

这意味着当你页面一加载，onChange就被调了一次。如果你的onChange里有打点上报、网络请求之类的逻辑，页面创建时就会误触发一次。

解决方案通常有两种：

第一种，加个标志位：

@State isInitialized: boolean = false;

onChange((index: number) => {
  if (!this.isInitialized) {
    this.isInitialized = true;
    return;
  }
  this.innerTabIndex = Number(index);
  this.reportTabSwitch(index);
})

第二种，把打点逻辑放到用户主动点击tabBar的事件里，而不是onChange里。onChange是被动通知，不区分触发来源。

我倾向第一种，简单直接。但要注意如果初始Tab不是0（比如通过深链接跳到第3个Tab），第一次onChange的index就不一定是0，所以标志位逻辑不能依赖index值。

TabContent默认全部加载：性能隐患

Tabs的TabContent默认是全部创建并加载的，不存在懒加载。也就是说，即使你的App有5个Tab，用户只看第一个Tab，后面4个Tab的内容也已经全部创建、build完成、挂在树上了。

Demo里有个动态计数器来验证这一点：

@Builder
tabPageContent(title: string, desc: string, tabIndex: number) {
  Column() {
    Text('动态计数: ' + this.dynamicCounter.toString())
      .fontSize(14)
      .fontColor('#007DFF')
      .margin({ top: 12 })
    Button('增加计数')
      .margin({ top: 8 })
      .onClick(() => {
        this.dynamicCounter++;
      })
  }
}

你在首页Tab点击"增加计数"，切到搜索Tab，搜索Tab里的计数也是同步增长后的值——因为它们共享同一个@State变量，而且所有TabContent都已经创建了。

如果某个Tab的内容很重（比如WebView、大量图片、复杂图表），全部预加载会导致首屏卡顿。解决方案：

  • 在TabContent里包一层if判断，只在当前Tab是激活Tab时才渲染内容
  • 用LazyForEach替代ForEach（但LazyForEach不支持在TabContent里直接使用，需要配合List）
  • 拆成独立页面用Navigation跳转，而不是放在同一个Tabs里

请添加图片描述

Tabs vs Swiper vs Navigation：选哪个？

TabViewDemo的对比指南给出了清晰的对比表：

特性 Tabs Swiper Navigation
主要用途 页签导航切换 轮播展示内容 页面路由管理
切换方式 点击页签/滑动 自动/手动滑动 路由跳转
内容预加载 默认全部加载 按需加载相邻项 按需加载
生命周期 共享Page生命周期 共享Page生命周期 独立Page生命周期
适用场景 主页导航/分类 Banner/引导页 页面跳转/返回

选型原则：

  • 底部导航栏 + 少量Tab → Tabs，没得选
  • Banner轮播、引导页 → Swiper，有自动播放和循环模式
  • 多级页面跳转、需要独立生命周期 → Navigation

特别注意生命周期的差异：Tabs和Swiper里的内容共享宿主页面的生命周期，不会触发onPageShow/onPageHide。Navigation的每个NavDestination是独立页面，有完整的页面生命周期。如果你的Tab内容需要独立的生命周期管理（比如切走时暂停视频、切回来时恢复），Navigation比Tabs更合适。

坑点汇总

  1. BarMode.Fixed限制Tab数量 — 超过5个Tab用Fixed模式会导致文字截断、布局拥挤，应改用Scrollable。

  2. TabContent默认非懒加载 — 所有TabContent在Tabs创建时全部build，重内容Tab会拖慢首屏。需要手动加if判断或拆成Navigation。

  3. onChange在创建时触发 — 初始化时onChange回调就被调用一次index=0，业务逻辑需要区分初始化触发和用户主动切换。

  4. 自定义tabBar需手动同步选中态 — 用@Builder自定义tabBar时，必须在onChange里更新当前index状态变量，builder里用这个变量做条件渲染，否则选中态不会跟着切换。

  5. Tabs的index参数不驱动切换 — Tabs({ index: xxx })只在首次创建时生效，后续改xxx不会自动切换Tab，必须用TabsController.changeIndex()。

  6. SymbolGlyph的fontColor接收数组 — 注意是[color]数组形式，不是直接传颜色字符串。写成.fontColor('#007DFF')不会生效，必须.fontColor(['#007DFF'])。

写在最后

Tabs组件的API设计给了灵活性但也给了坑——自定义tabBar的自由换来的是手动同步的负担，全量预加载换来的是简单但低效，选型前先把场景想清楚再动手。

# harmonyos # 华为 # 交互
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

HarmonyOS应用《民族图鉴》开发第40篇：服务层架构总结——设计模式与最佳实践全景

avatar HarmonyOS开发者社区
cover

打通鸿蒙系统生态入口：ArkTS 服务卡片 postCardAction 路由事件分发详解

avatar HarmonyOS开发者社区
cover

元服务视角下的多端体验扩展：构建轻量、即时响应的情绪反馈触点

avatar HarmonyOS开发者社区