HarmonyOS 沉浸光感（Immersive Light）入门指南：从平面到空间化的视觉跃迁

前言

在移动操作系统 UI 设计从拟物化到扁平化再到沉浸式设计的演进历程中，HarmonyOS 一直走在前沿。从 API 26.0.0 开始，HarmonyOS 正式引入了沉浸光感（Immersive Light）——这不是简单的光影特效叠加，而是一套完整的空间化视觉与动效体系。它通过模拟真实物理光照模型，在 UI 组件内部产生细腻的光晕、反射和折射效果，让界面元素从"扁平的像素排列"跃升为"具有深度、材质与温度的数字空间"。

本文作为沉浸光感系列的第一篇，将从设计理念、核心概念、六大视觉特性、四档分级体系到双轨适配架构，带你系统地理解沉浸光感的设计哲学与技术全貌。

一、空间化设计理念：从"贴纸"到"玻璃"

1.1 传统 UI 的视觉困境

在沉浸光感出现之前，移动应用的 UI 普遍存在以下视觉问题：

问题表现用户感知
贴纸式界面导航栏和标题栏是实心色块，与内容"硬贴"在一起缺乏层次感，像在看一张平面海报
交互反馈单调按钮点击只有颜色变化，没有光感和弹性觉得"点了张图"，缺乏真实触感
底部导航厚重底部导航栏占满一排，沉重的色块割裂内容压迫感强，浪费屏幕空间
空间感缺失叠加层（弹窗、菜单）与背景无材质区分无法感知 Z 轴深度，容易迷失

1.2 沉浸光感的设计哲学

沉浸光感的核心理念是"消除界面与内容之间的视觉割裂"。它借鉴了自然界中光线在不同介质间传播、折射、反射的物理规律，将界面元素设计为具备光学扩散与动态透光特性的数字介质：

在这里插入图片描述

图：沉浸光感设计理念——从平面贴纸（左）到通透玻璃质感（右）的视觉跃迁

关键洞察：沉浸光感的"沉浸"本质，不是"让界面变得更炫"，而是"让界面变得更自然"。光线在介质表面发生折射与漫反射，使界面背板如薄雾般轻盈悬浮于内容之上，前景与背景信息自然交融、和谐共生。

二、沉浸光感六大视觉特性

2.1 特性全景

沉浸光感赋予组件以下六大视觉特性，共同构成空间化视觉的基石：

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

2.2 沉浸光感的两大能力维度

沉浸光感包含两个核心能力维度：

  1. 沉浸式系统材质（ImmersiveMaterial）：通过影响组件的背景色 backgroundColor、边框颜色 borderColor、边框宽度 borderWidth、阴影 shadow 和材质滤镜 materialFilter，让组件呈现具有层次感和通透感的视觉表现。

  2. 空间动效：为 Dialog 弹窗和菜单控制等组件弹出过程增添形变、流光等动态表现，使动画更加灵动流畅。

2.3 技术原理简述

沉浸光感并非简单的 CSS 滤镜叠加，而是通过以下技术链路实现：

  • 背景采样：系统实时采样组件下方的内容像素，计算模糊区域
  • 光照模拟：基于物理光照模型，在 GPU 层面计算光晕、反射和折射
  • 算力自适应：根据设备芯片算力（高/中/低）自动调整渲染精度
  • 用户偏好映射：读取系统设置中用户选择的沉浸光感强度（强/均衡/弱），自动映射到对应参数

三、沉浸光感四档分级体系

3.1 档位总览

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

档位MaterialLevel 枚举说明适用场景
强EXQUISITE完整的沉浸光感效果，包含所有视觉特性高性能旗舰设备，视觉要求极高的场景
均衡（默认）GENTLE适度的沉浸光感效果，视觉效果与性能平衡大多数中高端设备，日常使用
弱SMOOTH轻量级沉浸光感效果，仅保留核心视觉特性低性能设备，保证流畅度优先
系统自适应ADAPTIVE由系统根据设备性能自动选择合适档位推荐大多数场景使用

3.2 档位选择策略

策略推荐度说明
使用 ADAPTIVE强烈推荐系统自动选档，在保证流畅度的同时达到最优视觉效果
手动指定档位谨慎使用需先调用 getSystemMaterialTypes() 查询设备支持能力，再进行优雅降级
强制使用 EXQUISITE不推荐低端设备可能导致卡顿和发热

3.3 设备算力与渲染效果的关系

设备算力对材质滤镜的影响对阴影的影响对背景色/边框的影响
高完整渲染，高精度模糊完整阴影效果不受影响
中完整渲染，高精度模糊完整阴影效果不受影响
低降级渲染简化阴影效果适度调整，保证可读性

重要提示：在绝大多数场景下，建议使用 ADAPTIVE（自适应）模式。系统会根据当前设备的算力和性能状态，自动选择最佳的光效表现。如果对视觉效果有极高要求，必须注意设备兼容性，强行在低端设备上开启可能导致卡顿和发热。

四、沉浸光感视觉样式层级

4.1 五种材质样式

为契合不同信息层级与交互场景，沉浸光感配备了从 ULTRA_THIN 到 ULTRA_THICK 共五个层级的 ImmersiveStyle 枚举值：

样式枚举值透明度推荐场景
超薄ULTRA_THIN极高透明度搜索框、小面积悬浮工具栏
薄THIN高透明度标题栏、顶部导航栏
常规REGULAR中等透明度卡片、面板背景（默认样式）
厚THICK较低透明度底部导航栏、模态面板
超厚ULTRA_THICK最低透明度弹出菜单、提示框

4.2 样式选择指南

在实际开发中，无需针对用户的三档自定义强度选项分别进行代码适配——系统底层将自动完成参数映射与动态渲染。只需一次定义，界面即可随用户设置平滑过渡。

不同位置或存在方式的交互组件推荐使用不同的材质档位：

  1. 顶部悬浮组件（标题栏、导航栏）：推荐 THIN 材质
  2. 底部悬浮组件（底部导航栏、工具栏）：推荐 THICK 材质
  3. 内容区叠加组件（卡片、面板）：推荐 REGULAR 材质
  4. 弹出层组件（菜单、对话框）：推荐 ULTRA_THICK 材质

五、双轨适配架构：HDS 组件 vs 普通 ArkUI 组件

5.1 双轨适配全景

沉浸光感的落地采用双轨适配方案，覆盖应用中所有组件的空间化需求：

在这里插入图片描述

图：沉浸光感双轨适配架构——HDS 组件与普通 ArkUI 组件统一收敛到 ImmersiveMaterial

轨道适用组件接入方式API 模块起始版本
轨道一：HDS 组件HdsNavigation、HdsTabs、MiniBar 等systemMaterialEffect 属性@kit.UIDesignKit（hdsMaterial）API 23（6.1.0）
轨道二：普通组件Column、Row、Button、弹窗等systemMaterial 属性@kit.ArkUI（uiMaterial）API 26.0.0

5.2 轨道一：HDS 组件适配

已使用 HDS 系列组件的应用，直接通过 systemMaterialEffect 配置材质，适配量最小：

  • HdsNavigation / HdsNavDestination：通过 TitleBarStyleOptions 的 systemMaterialEffect 参数设置标题栏光感
  • HdsTabs：通过 HdsTabsFloatingStyle 的 systemMaterialEffect 参数设置底部页签光感

5.3 轨道二：普通 ArkUI 组件适配

未接入 HDS 的普通 ArkUI 组件，通过 systemMaterial 通用属性开启材质：

  • 通过通用属性设置：.systemMaterial(new uiMaterial.ImmersiveMaterial()) 开启，.systemMaterial(undefined) 关闭
  • 通过组件独有接口设置：弹窗类组件支持通过自身的 systemMaterial 属性开启沉浸式系统材质

选型判断：只要组件来自 HDS 体系就用 systemMaterialEffect（hdsMaterial）；其余普通组件与弹窗用 systemMaterial（uiMaterial）。两条轨道最终都指向 ImmersiveMaterial，保证整页质感一致。

六、基础代码入门

6.1 应用级开启沉浸光感

在 module.json5 中配置应用级沉浸光感开关：

{
  "module": {
    "metadata": [
      {
        "name": "uiMaterial",
        "value": "true"
      }
    ]
  }
}

6.2 组件级开启：创建 IMMERSIVE 材质

import { uiMaterial } from '@kit.ArkUI';

// 创建一块薄型材质（THIN），适合搜索框和小面积悬浮工具栏
private readonly thinMaterial: uiMaterial.Material =
  new uiMaterial.ImmersiveMaterial({
    // THIN 具有较强的透明感，适合标题栏和搜索框
    style: uiMaterial.ImmersiveStyle.THIN,
    // 开启系统提供的按压形变
    interactive: true,
    // 开启触点光感，使用白色光感
    lightEffect: {
      color: Color.White
    }
  });

// 创建一块常规材质（REGULAR），适合卡片和面板
private readonly regularMaterial: uiMaterial.Material =
  new uiMaterial.ImmersiveMaterial({
    style: uiMaterial.ImmersiveStyle.REGULAR,
    interactive: true,
    lightEffect: {
      color: Color.White
    }
  });

// 创建一块厚材质（THICK），适合底部导航栏
private readonly thickMaterial: uiMaterial.Material =
  new uiMaterial.ImmersiveMaterial({
    style: uiMaterial.ImmersiveStyle.THICK,
    interactive: false
  });

6.3 将材质应用到组件

@Entry
@Component
struct ImmersiveLightDemo {
  build() {
    Column({ space: 16 }) {
      // 搜索框：使用 THIN 材质
      TextInput({ placeholder: '搜索内容...' })
        .width('90%')
        .height(48)
        .borderRadius(24)
        .systemMaterial(this.thinMaterial)

      // 内容卡片：使用 REGULAR 材质
      Column() {
        Text('沉浸光感卡片')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .fontColor('#333')
        Text('这是一张具有通透玻璃质感的卡片')
          .fontSize(14)
          .fontColor('#666')
          .margin({ top: 8 })
      }
      .width('90%')
      .padding(20)
      .borderRadius(16)
      .systemMaterial(this.regularMaterial)

      // 底部操作条：使用 THICK 材质
      Row({ space: 24 }) {
        Button('取消')
          .fontSize(16)
          .fontColor('#666')
          .backgroundColor(Color.Transparent)

        Button('确认')
          .fontSize(16)
          .fontColor(Color.White)
          .backgroundColor('#007AFF')
          .borderRadius(12)
          .width(120)
          .height(44)
      }
      .width('90%')
      .padding(16)
      .borderRadius(16)
      .systemMaterial(this.thickMaterial)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#F0F0F5')
  }
}

6.4 关闭材质效果

// 关闭某个组件的材质效果
.someComponent()
  .systemMaterial(undefined)  // 传入 undefined 即可关闭

6.5 应用级开启与组件级开启的优先级

/**
 * 沉浸光感优先级说明：
 * 1. module.json5 中的应用级开关控制全局
 * 2. 组件级 .systemMaterial() 覆盖全局设置
 * 3. 组件级 .systemMaterial(undefined) 关闭单个组件材质
 */
@Component
struct MaterialPriorityDemo {
  // 即使在 module.json5 中开启了应用级沉浸光感
  // 以下组件可以通过 systemMaterial 进行精细化控制

  build() {
    Column() {
      // 组件 A：使用 REGULAR 材质（覆盖全局默认）
      Text('组件 A - 毛玻璃效果')
        .systemMaterial(new uiMaterial.ImmersiveMaterial({
          style: uiMaterial.ImmersiveStyle.REGULAR
        }))

      // 组件 B：关闭材质（即使全局开启了）
      Text('组件 B - 无材质效果')
        .systemMaterial(undefined)

      // 组件 C：使用全局默认材质（不设置 systemMaterial）
      Text('组件 C - 跟随全局配置')
    }
  }
}

6.6 深浅色模式下的沉浸光感适配

import { uiMaterial } from '@kit.ArkUI';

/**
 * 深浅色模式自适应沉浸光感
 * 沉浸光感自动支持深浅色模式，无需手动适配
 * 但可以通过 lightEffect.color 进行微调
 */
@Component
struct DarkModeImmersiveLight {
  @StorageLink('currentColorMode')
  colorMode: number = 0;

  /**
   * 根据当前主题获取光感颜色
   */
  private getAdaptiveLightColor(): Color {
    // 深色模式：使用偏暖的光感颜色
    // 浅色模式：使用白色光感
    return this.colorMode === 0
      ? Color.White
      : Color.White;  // 沉浸光感自动处理反色，无需手动区分
  }

  private readonly adaptiveMaterial: uiMaterial.Material =
    new uiMaterial.ImmersiveMaterial({
      style: uiMaterial.ImmersiveStyle.REGULAR,
      interactive: true,
      lightEffect: { color: Color.White }  // 系统自动处理深浅色适配
    });

  build() {
    Column() {
      Text('沉浸光感自动适配深浅色模式')
        .fontSize(16)
        .fontColor('#333')
    }
    .width('90%')
    .padding(20)
    .borderRadius(16)
    .systemMaterial(this.adaptiveMaterial)
  }
}

七、设备能力探测与优雅降级

7.1 能力探测 API

在启用高级沉浸光感效果之前，应先探测设备能力：

import { hdsMaterial } from '@kit.UIDesignKit';

/**
 * 探测设备支持的材质类型
 */
private detectMaterialCapability(): void {
  try {
    const supportedTypes = hdsMaterial.getSystemMaterialTypes();
    console.info(`设备支持的材质类型: ${JSON.stringify(supportedTypes)}`);

    // 检查是否支持 EXQUISITE 级别
    const supportsExquisite = supportedTypes.some(
      (type: hdsMaterial.MaterialType) => type === hdsMaterial.MaterialType.EXQUISITE
    );

    if (supportsExquisite) {
      console.info('✅ 设备支持高级沉浸光感（EXQUISITE）');
    } else {
      console.info('⚠️ 设备不支持高级沉浸光感，将使用 ADAPTIVE 模式');
    }
  } catch (err) {
    console.error(`探测材质能力失败: ${JSON.stringify(err)}`);
  }
}

7.2 优雅降级策略

设备类型探测结果降级策略
旗舰设备支持 EXQUISITE使用 ADAPTIVE，系统自动使用最高档位
中端设备支持 GENTLE使用 ADAPTIVE，系统自动选择均衡档
低端设备仅支持 SMOOTH使用 ADAPTIVE，系统自动选择轻量档
不支持的设备返回空数组不开启沉浸光感，使用传统样式
/**
 * 安全获取沉浸光感材质等级
 */
private getSafeMaterialLevel(): hdsMaterial.MaterialLevel {
  if (!this.isImmersiveLightSupported()) {
    return hdsMaterial.MaterialLevel.SMOOTH; // 最低档位兜底
  }
  return hdsMaterial.MaterialLevel.ADAPTIVE; // 推荐自适应
}

/**
 * 检测设备是否支持沉浸光感
 */
private isImmersiveLightSupported(): boolean {
  try {
    const types = hdsMaterial.getSystemMaterialTypes();
    return types.length > 0;
  } catch (err) {
    return false;
  }
}

八、约束与限制

8.1 已知限制

在接入沉浸光感前，需要了解以下约束：

约束项说明解决方案
同层渲染场景API 23 及以前，Web 组件内嵌 ArkUI 控件时可能背景变透明关闭该控件的沉浸光感效果，或关闭同层渲染
亮色模式 + EXQUISITEEXQUISITE 材质可能覆盖白色叠层若底色为非白纯色，切换至 GENTLE 材质
属性冲突手动设置 backgroundColor 可能覆盖系统材质效果使用 systemMaterial 时避免手动设置 backgroundColor
性能功耗低端设备上高级光感效果可能增加功耗使用 ADAPTIVE 模式，让系统自动降级

8.2 设计原则

在实际应用中，应遵循以下原则：

  1. 内容为先：沉浸光感增强 UI 的同时不牺牲操作效率
  2. 体验至上：保证不同设备上的体验一致性，低端设备优雅降级
  3. 灵动交互：合理运用空间动效，让交互反馈更加自然

九、沉浸光感与空间化的关系

9.1 空间化全景

空间化（Spatial UI）是 HarmonyOS 在视觉体验层面的一次重要升级，它包含三大核心能力：

能力角色关键特性
沉浸光感材质空间化视觉的基石毛玻璃模糊、渐变模糊、弹性反馈、点光源、流光
悬浮组件空间化的交互载体底部导航栏悬浮圆角胶囊、MiniBar 折叠展开
智感握姿空间化的智能交互握持手感知、UI 自动跟随、左右自适应

9.2 三者协同关系

  1. 沉浸光感提供通透的玻璃质感，让悬浮组件"漂浮"在内容之上
  2. 悬浮组件利用沉浸光感材质，实现从传统贴底色块到悬浮胶囊的视觉升级
  3. 智感握姿驱动悬浮组件根据握持手自动切换位置，叠加智能交互

十、总结

本文作为沉浸光感系列入门篇，系统介绍了以下核心内容：

  • 设计理念：沉浸光感从"贴纸"到"玻璃"的视觉跃迁，消除界面与内容的视觉割裂
  • 六大特性：通透材质、渐变模糊、按压弹性反馈、按压点光源、材质流光、智能反色
  • 四档分级：EXQUISITE（强）、GENTLE（均衡）、SMOOTH（弱）、ADAPTIVE（自适应）
  • 五种样式：ULTRA_THIN 到 ULTRA_THICK 五个层级，适配不同信息层级
  • 双轨适配：HDS 组件（systemMaterialEffect）与普通 ArkUI 组件（systemMaterial）统一收敛到 ImmersiveMaterial
  • 基础代码：应用级开启、组件级创建材质、应用到组件、优雅降级

下一篇将深入讲解标题栏、底部导航、MiniBar 和内容区组件的沉浸光感实战适配。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

# harmonyos # 平面 # 华为
Logo
HarmonyOS开发者社区

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

更多推荐

问答嘉年华第二期「7.0 冲关季」正式开榜！带上你的 7.0 卡点，一起冲关

问答嘉年华是共创季中贯穿始终的线上问答活动，旨在搭建一个「有问必答、有答必奖」的技术互助平台。第二期我们聚焦。希望你带上升级过程中真实遇到的卡点来提问、来解答——那些文档没讲透、搜索查不到、最后只能自己啃源码的部分，恰恰是我们最想沉淀下来的内容。不再只看重问答条数，而是看你的答案有没有真的被人看见、认可、复用。同样的产出，用心写的好回答和不走心的应付，积分最多能拉开 3 到 5 倍。活动时间：20

avatar HarmonyOS开发者社区
cover

HarmonyOS 7 新特性2：音频编创——轻音台里的降噪、环绕与格式转换

avatar HarmonyOS开发者社区
cover

HarmonyOS 7.0 文搜图实战①：从“一句话找照片”开始

avatar HarmonyOS开发者社区