目录

沉浸光感

概述

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

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

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

沉浸光感介绍

[h2]什么是沉浸光感

沉浸光感是一套高品质视觉与动效体系。通过模拟真实物理光照模型,在UI组件内部产生细腻的光晕、反射和折射效果,从而打造出通透玻璃质感,提升应用的视觉沉浸感和交互反馈的真实度。它赋予组件以下视觉特性:

特性

说明

通透材质

组件背景呈现毛玻璃效果,内容可透过组件隐约可见,营造层次感与通透感。

渐变模糊

标题栏随页面滑动产生渐变模糊效果,从透明到模糊平滑过渡。

按压弹性反馈

用户按压组件时产生弹性缩放动画,提供触觉层面的反馈。

按压点光源

按压时在触点位置产生光晕扩散效果,增强交互的视觉反馈。

材质流光

组件表面呈现微妙的流光效果,随视角和状态变化,提升精致感。

智能反色

当底层内容颜色与组件前景色接近时,自动调整前景色以保证可读性。

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

[h2]沉浸光感的档位

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

档位

MaterialLevel枚举

说明

强

EXQUISITE

完整的沉浸光感效果,包含所有视觉特性,适合高性能设备。

均衡(默认)

GENTLE

适度的沉浸光感效果,在视觉效果与性能之间取得平衡。

弱

SMOOTH

轻量级沉浸光感效果,仅保留核心视觉特性,适合低性能设备。

系统自适应

ADAPTIVE

由系统根据设备性能自动选择合适的档位,推荐大多数场景使用。

  • 推荐使用默认值ADAPTIVE档位。该模式下,系统会根据当前设备的算力动态调整组件的材质效果,兼顾性能与显示效果。
  • 若未采用系统自适应能力,请先调用getSystemMaterialTypes()接口查询当前设备支持的材质能力,再根据查询结果选用相应的材质效果枚举:
    • 如果查询结果显示当前设备支持IMMERSIVE材质类型,可选用EXQUISITE或GENTLE效果。
    • 如果查询结果显示当前设备不支持IMMERSIVE材质类型,则建议使用SMOOTH效果,以降低卡顿和发热风险,保障用户体验。

沉浸光感效果由材质滤镜、折射、高光、阴影等多层效果叠加而成,渲染时需要消耗GPU资源,不合理使用会显著增加功耗。在实际应用中,总体原则是将沉浸光感效果作为一种"稀缺"视觉资源使用,具体参考沉浸光感功耗优化。

沉浸光感适配方案

沉浸光感的适配要从框架层面整体规划,核心策略是:

为有效实现沉浸光感效果,应遵循“从整体到局部”的适配原则:首先通过整体框架适配确立应用的基础视觉规范,为后续工作奠定基础;在此基础上,针对标题栏、底部导航及内容区域组件进行针对性调整,以确保视觉风格统一与交互体验连贯。

[h2]整体框架适配

  1. 采用HDS系列组件

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

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

  2. 普通组件开启沉浸光感

    组件开启沉浸光感可以查看组件适配沉浸光感,系统介绍各组件如何通过应用级开关与组件级配置开启沉浸光感,涵盖沉浸光感的视觉效果、设置方法及适配要点,帮助开发者快速完成沉浸光感的组件适配。

    本文通过组件级开启方式设置沉浸式系统材质,设置方式分三种方式开启:

    • 通过通用属性设置

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

      1. 开启效果:.systemMaterial(new uiMaterial.ImmersiveMaterial())或者.systemMaterial(undefined)
      2. 关闭效果:.systemMaterial(uiMaterial.Material.empty)
    • 通过组件专属接口设置

      当前支持设置的组件包括:Select下拉菜单的menuSystemMaterial、Navigation标题栏的systemMaterial。

    • 弹窗类组件通过options参数中的systemMaterial字段设置。
    • 开启沉浸光感,要确保应用的targetAPIVersion不低于26.0.0。如果低版本适配,适配指导请参考ArkTS API兼容性保护。
    • 沉浸光感开启后,除了弹窗类组件或方法、Slider、Toggle,其他组件仅在以下区域中生效:Navigation/NavDestination标题栏,或横向Tabs中barPosition为BarPosition.End的底部TabBar中。

      弹窗类组件或方法包括:Popup、Tips、Menu、BindSheet、showActionMenu、AlertDialog、CustomDialog、ActionSheet、CalendarPickerDialog、DatePickerDialog、TextPickerDialog、TimePickerDialog、Toast、Select、AlphabetIndexer气泡弹窗、Text设置copyOption后长按或双击触发的文本菜单、SelectionMenu(结合bindSelectionMenu一起使用)。

    • 沉浸光感开启后,需要大量GPU资源,具体的使用指导请参考沉浸光感功耗优化,其余开启后的常见问题请参考沉浸光感常见问题。

[h2]标题栏适配

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

[h2]底部导航适配

[h2]内容区域组件适配

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

沉浸光感开启后,除了弹窗类组件或方法、Slider、Toggle,其他组件仅在以下区域中生效:Navigation/NavDestination标题栏,或横向Tabs中barPosition为BarPosition.End的底部TabBar中。

效果示意图如下图所示:

场景一:应用首眼沉浸光感

应用首眼是用户打开应用的第一印象,沉浸光感能让首眼效果焕然一新。基于HDS提供的HdsNavigation与HdsTabs组件,通过配置沉浸光感材质,即可打造精致的首眼视觉效果。

首眼沉浸效果-强

首眼沉浸效果-均衡

首眼沉浸效果-弱

[h2]列表标题栏适配光感

[h2]首页底部导航适配

  1. 使用悬浮导航

    首页底部导航可通过HdsTabs悬浮模式实现,配置barFloatingStyle属性可自定义悬浮栏样式,包括圆角、背景色及位置偏移等参数,适配多设备布局需求。

    HdsTabs({ controller: this.controller }) {
      // ...
    }
    .scrollable(false)
    .barOverlap(true)
    .vertical(false)
    .barPosition(BarPosition.End)
    .onAttach(() => {
      try {
        this.controller.preloadItems([0, 1, 2, 3, 4]);
      } catch (error) {
        Logger.error(TAG, `OnAttach preloadItems failed`);
      }
    })
    .barFloatingStyle({
      barBottomMargin: this.globalInfoModel.naviIndicatorHeight > 0 ? this.globalInfoModel.naviIndicatorHeight :
        $r('sys.float.padding_level8'),
      adaptToHandedness: true,
      systemMaterialEffect: {
        materialType: hdsMaterial.MaterialType.ADAPTIVE,
        materialLevel: this.customMaterialLevel.level,
      }
    })

    MaterialLevel使用了this.customMaterialLevel.level,这意味着用户可以通过菜单动态切换沉浸光感的强度档位。

  2. 适配新材质

    悬浮导航栏的材质效果通过统一配置systemMaterialEffect的参数SystemMaterialParams,让标题栏与悬浮导航栏呈现出协调一致的光感视觉风格。

    HdsNavigation() {
      // ...
    }
    // ...
    .titleBar({
      // ...
      style: {
        // ...
        systemMaterialEffect: {
          materialType: hdsMaterial.MaterialType.ADAPTIVE,
          materialLevel: this.customMaterialLevel.level,
        },
      },
      // ...
    })
    // ...

[h2]菜单栏适配沉浸光感

菜单栏沉浸光感适配的核心是通过封装版本兼容的材质工具类,实现API级别的平滑过渡。菜单栏沉浸光感效果如下图所示:

场景二:自适应悬浮导航

自适应悬浮导航作为空间化核心交互能力,可通过HdsTabs的悬浮模式和MiniBar配置快速实现多设备适配,提升用户操作效率。效果示意如下图:

自适应悬浮-展开

自适应悬浮-折叠1

自适应悬浮-折叠2

[h2]沉浸式迷你栏

在音乐播放场景中,采用主HdsTabs与可折叠MiniBar的组合方案。MiniBar作为嵌入HdsTabs的迷你控制栏,可灵活切换折叠/展开状态。示例效果折叠时呈现紧凑播放控制条,展开时展示完整播放信息与控制按钮,实现空间高效利用与操作便捷性的统一。

  1. 设置悬浮导航布局位置与层级叠加
    • 设置barPosition为BarPosition.End且vertical为false,使页签栏置于容器底部。
    • 设置barOverlap为true,使页签栏悬浮于内容之上。
  2. 设置沉浸光感

    设置barFloatingStyle的materialType材质效果与materialLevel材质等级均为自适应(ADAPTIVE)模式。

  3. 设置迷你栏

    通过barFloatingStyle方法的miniBar属性自定义迷你栏。

import {
  HdsBarStyle,
  hdsMaterial,
  HdsNavDestination,
  HdsTabs,
  HdsTabsController,
  ScrollEffectType,
} from '@kit.UIDesignKit';
// ...
  private controller: HdsTabsController = new HdsTabsController();
  @Local globalInfoModel: GlobalInfoModel =
    AppStorageV2.connect(GlobalInfoModel, StorageKey.GLOBAL_INFO) ?? new GlobalInfoModel();
  @Local isMiniBar: boolean = true;

  @Builder
  miniBarBuilder() {
    Row() {
      // ...
    }
  }
  // ...
      HdsTabs({ controller: this.controller }) {
        // ...
      }
      .barOverlap(true)
      .vertical(false)
      .barPosition(BarPosition.End)
      .barFloatingStyle({
        barBottomMargin: this.globalInfoModel.naviIndicatorHeight > 0 ? this.globalInfoModel.naviIndicatorHeight :
          $r('sys.float.padding_level8'),
        systemMaterialEffect: {
          materialType: hdsMaterial.MaterialType.IMMERSIVE,
          materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE
        },
        miniBar: {
          miniBarBuilder: () => this.miniBarBuilder(),
          onBarStyleChange: (miniBarStyle: HdsBarStyle) => {
            this.isMiniBar = miniBarStyle === HdsBarStyle.COLLAPSE
          }
        }
      })
      // ...

[h2]多设备左右栏适配

MiniBar可根据设备宽度自动适配展开/折叠状态:宽屏设备(如平板)默认展开,窄屏设备(如手机)默认折叠,无需开发者手动干预。

场景三:智感握姿,智能交互

智感握姿是空间化在交互层面的核心能力。在宽屏设备上,基于智能感知用户握持,底部悬浮导航栏会自动跟随握持手左右切换位置,提供智能化交互体验。具体开发者请查看智感握姿。

示例代码