效果

一、整体架构概览

Index.ets
├── 模块导入（@kit.UIDesignKit）
├── @ComponentV2 组件声明
│   ├── 状态管理（@Local）
│   ├── 生命周期初始化（aboutToAppear → 沉浸光感降级检测）
│   ├── TabBar @Builder（4 个页签栏构建器）
│   ├── 页面内容 @Builder（4 个内容区构建器）
│   ├── 迷你栏 @Builder（miniBarBuilder）
│   └── build() → HdsTabs 配置
│       ├── 悬浮布局基础属性
│       ├── .barFloatingStyle() 悬浮样式
│       │   ├── systemMaterialEffect（沉浸光感）
│       │   ├── gradientMask（渐变遮罩）
│       │   └── miniBar*（迷你栏配置）
│       └── 事件回调

二、实现流程步骤

步骤 1：导入设计工具包模块

import { HdsTabs, HdsTabsController, hdsMaterial } from '@kit.UIDesignKit';

• HdsTabs：HDS 设计规范增强版 Tabs 组件，支持悬浮样式和沉浸光感
• HdsTabsController：控制器，用于编程式操控页签切换和迷你栏状态
• hdsMaterial：沉浸光感材质效果工具模块，提供材质类型枚举和设备能力查询

步骤 2：声明 V2 状态变量

@Entry
@ComponentV2
struct Index {
  @Local currentTabIndex: number = 0;
  @Local customMaterialType: hdsMaterial.MaterialType = hdsMaterial.MaterialType.ADAPTIVE;
  @Local customMaterialLevel: hdsMaterial.MaterialLevel = hdsMaterial.MaterialLevel.ADAPTIVE;
  private hdsTabController: HdsTabsController = new HdsTabsController();
}

关键点：

• 使用 @ComponentV2 + @Local 遵循项目 V2 状态管理规范
• currentTabIndex 追踪当前选中页签，驱动 TabBar 图标/文字选中态切换
• customMaterialType / customMaterialLevel 使用 @Local 装饰，因为 initMaterialEffect() 可能在运行时修改它们（降级适配），修改后需驱动 UI 刷新
• hdsTabController 不参与 UI 渲染，使用普通 private 变量

步骤 3：沉浸光感降级检测

aboutToAppear(): void {
  this.initMaterialEffect();
}

private initMaterialEffect(): void {
  const supportedTypes: Array<hdsMaterial.MaterialType> = hdsMaterial.getSystemMaterialTypes();
  if (!supportedTypes.includes(hdsMaterial.MaterialType.IMMERSIVE)) {
    this.customMaterialType = hdsMaterial.MaterialType.NONE;
    this.customMaterialLevel = hdsMaterial.MaterialLevel.SMOOTH;
  }
}

关键点：

• hdsMaterial.getSystemMaterialTypes() 查询当前设备支持的材质类型列表
• 若设备不支持 IMMERSIVE（沉浸光感），则降级为 NONE+ SMOOTH（流畅级别），保证低端设备不卡顿
• 此逻辑放在 aboutToAppear() 而非 build() 中，符合"build() 保持纯声明式"的规范

步骤 4：构建 TabBar 页签项

@Builder
homeTabBar() {
  Column() {
    SymbolGlyph(this.currentTabIndex === 0 ? $r('sys.symbol.house_fill')
        : $r('sys.symbol.house'))
        .width(24)
        .height(24)
        .fontColor(this.currentTabIndex === 0 ? ['#007DFF'] : ['#182431'])
        .margin({ left: 7 })
    Text('首页')
      .fontSize(10)
      .fontColor(this.currentTabIndex === 0 ? '#007DFF' : '#182431')
      .margin({ top: 2 })
  }
  .justifyContent(FlexAlign.Center)
  .alignItems(HorizontalAlign.Center)
}

关键点：

• 每个页签对应独立的 @Builder 函数，通过 currentTabIndex 精确匹配索引判断选中态
• 使用 $r('sys.symbol.*') 引用系统图标资源，保证图标风格与系统一致
• 选中/未选中通过图标资源切换（fill/outline）和颜色切换实现

步骤 5：构建迷你栏

@Builder
miniBarBuilder() {
  Row() {
    Image($r('sys.media.ohos_ic_public_more'))
      .width(24)
      .height(24)
      .fillColor('#182431')
      .margin({ left: 4, right: 8 })

    Text('快捷操作')
      .fontSize(14)
      .fontColor('#182431')
      .margin({ left: 8 })
  }
  .padding({ left: 12, right: 12, top: 8, bottom: 8 })
}

关键点：

• 核心操作按钮放置在左侧，确保迷你栏折叠时按钮仍然可见
• **不要给迷你栏根节点设置 width('100%')**，否则收起动画会失效

步骤 6：配置 HdsTabs 悬浮样式与沉浸光感

HdsTabs({ controller: this.hdsTabController }) {
  // TabContent...
}
.barOverlap(true)               // 内容区与页签栏重叠（悬浮前提）
.barPosition(BarPosition.End)   // 页签栏位于底部
.vertical(false)                 // 水平排列
.barFloatingStyle({
  barBottomMargin: 16,           // 页签栏底部间距
  gradientMask: {                // 渐变遮罩
    maskColor: '#66F1F3F5',
    maskHeight: 92
  },
  systemMaterialEffect: {        // 沉浸光感
    materialType: this.customMaterialType,
    materialLevel: this.customMaterialLevel
  },
  // 设置迷你栏，若不设置，则仅有页签栏。
  miniBar: {
    miniBarBuilder: () => this.miniBarBuilder()
  }
})

三、.barFloatingStyle() 核心配置详解

配置项	作用	关键值
barBottomMargin	页签栏距屏幕底部距离	16vp
gradientMask	页签栏上方渐变遮罩，柔化内容过渡	maskColor/maskHeight
systemMaterialEffect	沉浸光感材质效果	materialType + materialLevel
miniBarBuilder	迷你栏自定义 UI 构建器	@Builder 函数引用
miniBarStyle	迷你栏初始状态：1=展开，0=折叠	仅在宽度 < 600vp 时生效
miniBarWidth	迷你栏展开宽度档位，最多 328vp	数组，按断点适配
enableMiniBarBackground	迷你栏背景自动同步页签栏	true
enableMiniBarClip	折叠时裁剪溢出内容	true（防止文字露出）

四、沉浸光感 materialType / materialLevel 枚举

MaterialType（材质类型）：

枚举值	含义	适用场景
ADAPTIVE	系统自适应调度	官方推荐默认值
IMMERSIVE	物理光照模型沉浸光感	高端设备，最佳视觉效果
BACKGROUND_BLUR	背景模糊降级方案	低端设备降级
NONE	无材质效果	不需要光感时

MaterialLevel（材质级别）：

枚举值	含义	性能影响
ADAPTIVE	系统自适应	系统调度
EXQUISITE	精致级，最强高光反馈	最高
GENTLE	温和级，效果收敛	中等
SMOOTH	流畅级，侧重性能	最低

五、版本要求

• 沉浸光感需 API 23（HarmonyOS 6.1.0）及以上
• 迷你栏在 HdsTabs 宽度小于 600vp 时自动生效
• 建议通过 hdsMaterial.getSystemMaterialTypes() 做运行时检测，确保低端设备优雅降级全部任务已完成。上面是完整的实现流程操作指南和关键代码讲解。

总结核心实现要点：

1. 悬浮样式：通过 .barOverlap(true) + .barPosition(BarPosition.End) + .barFloatingStyle() 三件套实现页签栏悬浮于内容区之上
2. 沉浸光感：在 barFloatingStyle 的 systemMaterialEffect 中配置 materialType 和 materialLevel，并通过 hdsMaterial.getSystemMaterialTypes() 在 aboutToAppear() 中做设备能力检测和降级适配
3. 迷你栏：通过 miniBarBuilder 传入自定义 UI，核心按钮放左侧保证折叠可见，enableMiniBarClip: true 防止折叠时文字溢出，且不设 width('100%') 以免收起动画失效
4. 状态管理：全程使用 @ComponentV2 + @Local 的 V2 模式，符合项目技术栈规范