手把手教你玩转HDS沉浸光感效果

鸿蒙开发干货——手把手教你玩转HDS沉浸光感效果

大家好，我是青蓝逐码的云杰。

最近有不少用户在交流时间到，应用底部 Tab 栏那种高级的“发光”和“沉浸”质感是怎么做出来的？

在鸿蒙应用开发中，细腻的光影和材质表现确实是提升 UI 质感、打造沉浸式体验的关键一环。无论是底部 Tab 栏的毛玻璃光感，还是顶部导航栏的高级光效，掌握系统级材质能力都能让你的应用瞬间“高大上”。本文将带你解锁鸿蒙开发中 HDS（HarmonyOS Design System）沉浸光感材质 的全流程技巧，附完整代码示例和降级适配指南，让你的应用轻松玩转高级光影效果。

一、沉浸光感是什么？

从 HarmonyOS 6.1.0(23) 版本开始，@kit.UIDesignKit 为 HDS 组件引入了强大的 systemMaterialEffect（系统材质效果）能力。其中最吸引人的就是沉浸光感（IMMERSIVE）。

与传统的纯色或简单的毛玻璃不同，沉浸光感会在组件内部模拟真实的物理光照模型。当你点击或与之交互时，会产生细腻的“光晕”和“反射”反馈，极大地增强了控件的立体感和触控反馈的真实度。

最近，我也在我的应用 「取件伙伴」 中上线了这种效果。先来看看最终在「取件伙伴」中的实现效果

目前，这套能力主要应用于两大核心组件：

1. HdsNavigation：可为标题栏（TitleBar）设置沉浸光感。
2. HdsTabs：可为底部的悬浮页签（TabBar）设置沉浸光感。

二、实战演练：为底部悬浮页签添加沉浸光感

接下来，我们以底部的 HdsTabs 为例，一步步实现沉浸光感效果。

1. 基础配置与准备

首先，确保你的工程引入了 UIDesignKit 相关的模块。我们需要 HdsTabs、HdsTabsController 以及 hdsMaterial。

import { hdsMaterial, HdsTabs, HdsTabsController } from "@kit.UIDesignKit";
import { SymbolGlyphModifier } from "@kit.ArkUI";

同时，我们定义好 Tab 栏的菜单配置（使用系统 Symbol 图标，支持多色渲染）：

interface MenuItem {
  symbolGlyph: SymbolGlyphModifier;
  symbolGlyph1: SymbolGlyphModifier;
  label: string;
}

const MENU_CONFIG: MenuItem[] = [
  {
    symbolGlyph: new SymbolGlyphModifier($r("sys.symbol.clock"))
      .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
      .fontColor([
        $r("sys.color.ohos_id_color_bottom_tab_icon_off"),
        $r("sys.color.ohos_id_color_bottom_tab_icon_auxcolor_off02"),
      ]),
    symbolGlyph1: new SymbolGlyphModifier($r("sys.symbol.clock_fill"))
      .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
      .fontColor([
        $r("app.color.primary_blue"),
        $r("sys.color.ohos_id_color_primary_contrary"),
      ]),
    label: "待取",
  },
  // ... 其他 Tab 项配置
];

2. 核心方案一：使用系统自适应沉浸光感（官方推荐）

在绝大多数场景下，我们推荐使用 ADAPTIVE（自适应）模式。系统会根据当前设备的算力和性能状态，自动为你选择最佳的光效表现，保证流畅度的同时达到最优的视觉效果。

@Entry
@Component
struct Index {
  private hdsTabsController: HdsTabsController = new HdsTabsController();

  build() {
    HdsTabs({ controller: this.hdsTabsController }) {
      ForEach(MENU_CONFIG, (item: MenuItem, index: number) => {
        TabContent() {
          // 这里放你的页面内容，比如 PackagesPage()
        }
        .tabBar(new BottomTabBarStyle({
          normal: item.symbolGlyph,
          selected: item.symbolGlyph1
        }, item.label).labelStyle({
          selectedColor: $r('app.color.primary_blue') // 设置文字高亮色
        }))
      })
    }
    .barOverlap(true) // 允许内容延伸到 Tab 栏底部
    .barPosition(BarPosition.End)
    // 核心配置：开启悬浮样式并设置自适应材质
    .barFloatingStyle({
      barBottomMargin: 28,
      systemMaterialEffect: {
        materialType: hdsMaterial.MaterialType.ADAPTIVE,
        materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE
      }
    })
  }
}

在这段代码中，最核心的就是 barFloatingStyle 里的 systemMaterialEffect 属性。我们将类型和级别都交给了系统 ADAPTIVE 去决策。

3. 核心方案二：强制自定义沉浸光感效果与降级处理

如果你对视觉有极高的要求，希望在支持的设备上强制开启最顶级的沉浸光效（例如点击时出现明显的“白光”反馈），你可以手动指定材质类型和级别。

避坑指南：并不是所有设备都支持高级的沉浸光感（IMMERSIVE）。如果强行在低端设备上开启，可能会导致严重的卡顿和发热。因此，必须先通过 API 查询设备能力，再进行优雅降级。

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

@Entry
@Component
struct Index {
  private hdsTabsController: HdsTabsController = new HdsTabsController();
  // 默认我们想用最精致的效果
  @State customMaterialLevel: hdsMaterial.MaterialLevel = hdsMaterial.MaterialLevel.EXQUISITE;
  @State customMaterialType: hdsMaterial.MaterialType = hdsMaterial.MaterialType.IMMERSIVE;

  aboutToAppear(): void {
    // 1. 查询当前设备支持的系统材质类型
    let materialTypes: Array<hdsMaterial.MaterialType> = hdsMaterial.getSystemMaterialTypes();

    // 2. 检查是否支持 IMMERSIVE (沉浸光感)
    if (materialTypes.indexOf(hdsMaterial.MaterialType.IMMERSIVE) < 0) {
      // 3. 如果不支持，进行降级处理，使用基础的背景模糊平滑效果
      this.customMaterialType = hdsMaterial.MaterialType.BACKGROUND_BLUR;
      this.customMaterialLevel = hdsMaterial.MaterialLevel.SMOOTH;
    }
  }

  build() {
    HdsTabs({ controller: this.hdsTabsController }) {
      // ... TabContent 配置与之前相同
    }
    .barFloatingStyle({
      barBottomMargin: 28,
      systemMaterialEffect: {
        materialType: this.customMaterialType, // 应用查询后的类型
        materialLevel: this.customMaterialLevel // 应用查询后的级别
      }
    })
  }
}

关于材质级别的选择：

• EXQUISITE (精致)：光影反馈最强烈、最细腻（比如点击时有明显点光源照射的高亮白光），但对性能要求最高。
• GENTLE (柔和)：光影反馈相对柔和内敛。
• SMOOTH (平滑)：性能开销最低，通常用于不支持复杂光照的降级场景。

三、总结

通过上述两种方案，我们可以非常轻松地为鸿蒙应用接入极具高级感的 HDS 沉浸光感材质。

• 追求稳定和省心：无脑选择 ADAPTIVE。
• 追求极致视觉体验：使用 IMMERSIVE + EXQUISITE，但切记一定要做设备能力查询和降级处理（hdsMaterial.getSystemMaterialTypes()），这是保证用户体验底线的关键。

同时，别忘了结合 deviceInfo.sdkApiVersion >= 23 来做好旧版本系统的兼容。

掌握了这些，你的应用 UI 质感绝对能上一个大台阶。赶紧去代码里试试吧！如果有任何疑问，欢迎在评论区交流。