鸿蒙6.0应用开发——沉浸光感效果实现

概述

空间化（Spatial UI）是HarmonyOS系统在视觉体验层面的一次重要升级。它通过沉浸光感材质与悬浮组件两大核心能力，让应用界面呈现出精致、通透、有层次的视觉效果，同时配合智感握姿等智能交互，全面提升UX的精致程度。

沉浸光感是空间化视觉的基石，为组件（标题栏、导航栏、工具栏等）提供三种视觉效果：内容相关的毛玻璃模糊、按压状态的弹性光效反馈、以及滑动过程的透明度渐变。悬浮组件则是空间化的交互载体，底部导航栏从传统的贴底色块变为悬浮圆角胶囊，配合MiniBar折叠展开、智感握姿左右跟随等能力，让交互更加自然流畅。空间化的效果如下所示：

本文将从沉浸光感的基础概念切入，重点围绕首眼沉浸光感、自适应悬浮导航与智感握姿智能交互三大应用场景，系统介绍如何在HarmonyOS应用中快速接入沉浸光感能力。

沉浸光感介绍

什么是沉浸光感

沉浸光感是HDS(HarmonyOS Design System)提供的一套全新材质体系。通过模拟真实物理光照模型，在UI组件内部产生细腻的光晕、反射和折射效果，从而打造出通透玻璃质感，提升应用的视觉沉浸感和交互反馈的真实度。它赋予组件以下视觉特性：

特性	说明
通透材质	组件背景呈现毛玻璃效果，内容可透过组件隐约可见，营造层次感与通透感。
渐变模糊	标题栏随页面滑动产生渐变模糊效果，从透明到模糊平滑过渡。
按压弹性反馈	用户按压组件时产生弹性缩放动画，提供触觉层面的反馈。
按压点光源	按压时在触点位置产生光晕扩散效果，增强交互的视觉反馈。
材质流光	组件表面呈现微妙的流光效果，随视角和状态变化，提升精致感。
智能反色	当底层内容颜色与组件前景色接近时，自动调整前景色以保证可读性。

沉浸光感视觉示意图如下所示：

沉浸光感的档位

为应对不同设备的性能差异，沉浸光感提供了多个档位供开发者选择：

档位	MaterialLevel枚举	说明
强	EXQUISITE	完整的沉浸光感效果，包含所有视觉特性，适合高性能设备。
均衡（默认）	GENTLE	适度的沉浸光感效果，在视觉效果与性能之间取得平衡。
弱	SMOOTH	轻量级沉浸光感效果，仅保留核心视觉特性，适合低性能设备。
系统自适应	ADAPTIVE	由系统根据设备性能自动选择合适的档位，推荐大多数场景使用。

说明

在绝大多数场景下，建议使用ADAPTIVE（自适应）模式。系统会根据当前设备的算力和性能状态，自动选择最佳的光效表现，在保证流畅度的同时达到最优视觉效果。如果对视觉效果有极高要求，可以手动指定材质类型和级别，例如强制使用EXQUISITE（精致）级别。但必须注意设备兼容性，因为并非所有设备都支持高级沉浸光感。强行在低端设备上开启可能导致卡顿和发热。因此，需要getSystemMaterialTypes()先查询设备支持的能力，再进行优雅降级。沉浸光感代表了HarmonyOS在空间、光影与交互设计上的新思考，合理运用能显著提升应用质感。

注意事项与限制

• 同层渲染场景限制：在API 23及以前版本的SDK中，同层渲染场景下设置沉浸光感效果可能导致控件背景变透明（如Web组件内嵌ArkUI控件）。此时建议在对应控件上关闭沉浸光感效果，或关闭同层渲染。
• 设计原则：在实际应用中，应遵循“内容为先、体验至上、灵动交互”的原则，确保沉浸光感增强UI的同时不牺牲操作效率。
• 适配多种场景：沉浸光感可以扩展到音量条、搜索框、各种按钮等更多控件，打造全场景一致的高级视觉体验。但在亮色模式下，EXQUISITE材质可能会覆盖白色叠层，若底色为非白纯色，可考虑切换至GENTLE材质。

沉浸光感适配方案

沉浸光感的适配要从框架层面整体规划，核心策略是：优先采用HDS系列组件替代传统组件以直接获得沉浸效果，而普通组件则通过systemMaterial通用属性进行配置。

整体框架适配

1. 优先采用HDS系列组件

   应用需要将传统的Navigation、Tabs等组件替换为HDS系列组件：

   • HDS导航（HdsNavigation/HdsNavDestination）：通过设置TitleBarStyleOptions的systemMaterialEffect参数，可为标题栏按钮设置沉浸光感视效。
   • HDS底部页签（HdsTabs）：通过设置HdsTabsFloatingStyle的systemMaterialEffect参数，可为底部页签设置沉浸光感视效。

   已采用HDS系列组件的应用，即可通过systemMaterialEffect属性配置沉浸光感效果，且始终跟随最新规范，大大减少了适配工作量。

2. 普通组件接入沉浸光感

   通过设置组件的systemMaterial属性来开启新材质效果。该属性本身是一个开关：

   • 开启效果：.systemMaterial(new uiMaterial.ImmersiveMaterial())
   • 关闭效果：.systemMaterial(undefined)

   说明

   为保证性能与体验的平衡，沉浸光感效果会根据设备算力自动进行分级渲染，这意味着同一材质在不同性能的设备上会呈现差异化的视觉效果。具体参数分级策略请参阅 ImmersiveMaterial类的官方文档。

标题栏适配

标题栏是沉浸光感最直观的体现。沉浸光感标题栏示意图如下图所示：

• 标题栏使用材质

  通过HdsNavigation或HdsNavDestination的titleBar属性，可以配置标题栏的滚动效果与材质效果。

  import { hdsMaterial, HdsNavigation，ScrollEffectType } from '@kit.UIDesignKit';
  
  private pathStack: NavPathStack = new NavPathStack();
  
  HdsNavigation(this.pathStack) {
    // Page content...
  }
  .titleBar({
    style: {
      scrollEffectOpts: {
        enableScrollEffect: true,
        scrollEffectType: ScrollEffectType.GRADIENT_BLUR,
      },
      systemMaterialEffect: {
        materialType: hdsMaterial.MaterialType.ADAPTIVE,
        materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE,
      },
    },
  })
  

  关键属性说明：

  属性	值	说明
  scrollEffectType	GRADIENT_BLUR	渐变模糊效果，标题栏随滑动从透明渐变为模糊。
  materialType	ADAPTIVE	自适应材质类型，系统根据场景自动选择材质风格。
  materialLevel	ADAPTIVE	自适应材质强度，系统根据设备性能自动选择档位。

  说明

  渐变模糊效果对比：

  • IMMERSIVE_GRADIENT_BLUR（沉浸光感渐变模糊）：标题栏从完全透明渐变到模糊，模糊区域更大，过渡更自然，沉浸感更强。配合材质效果，呈现通透的视觉体验。
  • GRADIENT_BLUR（渐变模糊）：标题栏从半透明渐变到模糊，过渡相对克制。配合材质效果，在通透与信息密度之间取得平衡。

  两种效果都需要配合systemMaterialEffect材质属性使用，才能呈现完整的沉浸光感效果.

• 标题栏和状态栏适配滑动显隐

  在沉浸光感页面中，标题栏和状态栏支持滑动隐藏，具体可参考标题栏动态显隐。具体实现方案如下：

  1. 通过dynamicHideTitleBar属性的hideTitleArea和hideStatusBar分别启动标题栏、状态栏的动态显隐功能。
  2. 通过dynamicHideTitleBar属性的mode设置动态显隐模式，HideMode支持三种模糊模式（SCROLL_UP_TO、SCROLL_UP、SCROLL_DOWN）以及混合模式（SCROLL_UP_TO_BLEND_SCROLL_UP）。
  3. 调用bindToScrollable接口绑定内容区滚动组件，实现标题栏和状态栏模糊度与透明度的同步变化。

  import { HdsNavigation, HideMode } from '@kit.UIDesignKit';
  
  scroller: Scroller = new Scroller();
  
  HdsNavDestination()
    .dynamicHideTitleBar({
      hideTitleArea: true,
      hideStatusBar: true,
      mode: HideMode.SCROLL_UP_TO,
    })
    .bindToScrollable([this.scroller])
  

底部导航适配

• 设置悬浮导航

  设置barOverlap(true)以启用悬浮模糊背景，通过barFloatingStyle配置悬浮样式，可将HdsTabs切换为悬浮胶囊形态，并通过barBottomMargin调整与内容区域的间距，增强视觉轻盈感。

  import { hdsMaterial, HdsTabs, HdsTabsController } from '@kit.UIDesignKit';
  
  private controller: HdsTabsController = new HdsTabsController();
  
  HdsTabs({ controller: this.controller }) {
    // TabContent...
  }
  .barOverlap(true)
  .vertical(false)
  .barPosition(BarPosition.End)
  .barFloatingStyle({
    barBottomMargin: 36,
    adaptToHandedness: true,
  })
  

  悬浮导航示意图如下：

  

• 设置沉浸光感效果

  悬浮导航栏的沉浸光感效果可通过barFloatingStyle中的systemMaterialEffect属性进行配置，其中materialType用于定义材质风格，materialLevel则控制材质强度。

  .barFloatingStyle({
    systemMaterialEffect: {
      // ...
      materialType: hdsMaterial.MaterialType.ADAPTIVE,
      materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE,
    }
  })
  

  沉浸光感示意图如下：

  

• 沉浸式MiniBar

  针对悬浮导航的多功能场景，例如音乐播放等需同时展示底部导航和播放控制的场景，HdsTabs提供了MiniBar能力，即在底部导航栏中嵌入一个可折叠展开的迷你栏。

  1. 设置HdsTabs布局位置barPosition和层级叠加barOverlap之后，通过barFloatingStyle方法的miniBar属性允许开发者自定义一个悬浮于屏幕底部的迷你控制中心。
  2. miniBarBuilder的配置通过@Builder装饰器来创建自定义的迷你栏。

  import { HdsTabs } from '@kit.UIDesignKit';
  
  @Builder
  buildCustomMiniBar() {
    Row() {
       // MiniBar UI
    }
  }
  
  HdsTabs()
    .barOverlap(true)  // Control the distance of the floating bar from the bottom of the screen.
    .barPosition(BarPosition.End)
    .barFloatingStyle({
      barBottomMargin: 28, // Allow content to overlap with the bar to achieve an immersive effect.
      miniBar: {
        miniBarBuilder: () => this.buildCustomMiniBar(), // Customize MiniBar content.
      }
    })
  

  MiniBar示意图如下图所示：

  

内容区域组件适配

对于内容区域中的普通组件，可通过设置其systemMaterial属性为ImmersiveMaterial实例来启用新材质效果。支持三个关键参数配置：

• style: 用于定义材质视觉样式，可选值详见ImmersiveStyle枚举。
• interactive：控制是否启用交互形变效果。
• lightEffect：用于配置光感交互反馈效果。

.systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA_THIN,
            interactive: true,
            lightEffect: { color: undefined }
 }))

效果示意图如下图所示：