前言

一、五档样式的差异应该看什么

二、组件的位置和面积为什么会改变选择

顶部悬浮区域可以先试 ULTRA_THIN

搜索框和底部操作栏可以先试 THIN

普通悬浮卡片可以从 REGULAR 开始

菜单和临时浮层可以先试 THICK

弹窗和半模态页面可以先试 ULTRA_THICK

三、怎样搭建一个可比较的最小页面

先创建五个材质对象

再让五张卡片共用同一套结构

四、模拟器中的五档样式为什么看起来一样

搜索框可以比较三档

底部操作栏需要看按钮数量

普通卡片可以把 REGULAR 当作起点

菜单可以比较三档

弹窗和半模态页面需要关注整体重量

总结

完整代码

Main.ets

前言

在之前接口和开关都确认以后，普通组件已经具备显示沉浸材质的基本条件。

接下来，开发者很快就会遇到一个更具体的问题：五档 ImmersiveStyle 应该怎样选择。

ULTRA_THIN、THIN、REGULAR、THICK 和 ULTRA_THICK 的名称看起来很直观。刚开始接入时，大家通常会根据“薄”和“厚”直接做决定，例如工具栏使用薄材质，弹窗使用厚材质，页面能正常显示以后就继续开发。

我第一次比较这五档材质时，也采用过这种方式。后来把五张卡片放在相同背景、尺寸和文字条件下对比，我才逐渐发现，材质厚度只是选择依据之一。组件面积、所在位置、背景复杂度和前景信息量，同样会改变最终结果。

材质逐渐变厚以后，背景细节会不断减弱，前景内容会更加稳定，组件在页面中的视觉重量也会增加。搜索框使用过厚材质时，页面可能显得沉重；大面积浮层使用过薄材质时，背景内容又容易干扰文字和操作。

因此，这一轮测试继续控制变量。五张卡片使用相同的背景、尺寸、圆角和文字，只修改 ImmersiveStyle。先看清五档样式的变化，再回到搜索框、工具栏、菜单和弹窗中做选择。

目前我的测试设备还没有 HarmonyOS 7 实机测试权限，本篇先使用模拟器核对接口和基础效果。具备相应权限时，大家应优先在真机上复核材质表现。

一、五档样式的差异应该看什么

ImmersiveStyle 从 API 26.0.0 开始提供，它定义了五种沉浸式材质样式。每一种样式都对应一组系统管理的材质参数，开发者通过枚举选择整体厚度，无需自行组合模糊、高光和阴影等效果。

从这张表看，五档样式形成了一条从通透到模糊的变化路径。不过，实际观察时还要同时看背景、前景和组件本身。

第一项是背景还剩多少信息。背景中的颜色分界、图案和文字越容易辨认，材质就越轻薄。对于需要延续页面内容的悬浮工具栏，这种通透感比较重要。

第二项是前景内容是否稳定。材质变厚以后，背景对文字和图标的干扰会逐渐降低。菜单、弹窗和信息量较大的浮层，更需要稳定的前景区域。

第三项是组件在页面中显得多重。同一张卡片使用 ULTRA_THIN 时会比较轻，使用 ULTRA_THICK 时会形成更明确的层级。组件面积越大，这种视觉重量的变化通常越明显。

除了样式本身，设备能力也会影响结果。style 参数主要影响高算力和中算力设备，系统会结合设备分档调整实际表现。用户设置的沉浸光感强度也会影响透明度、对比度、折射和环境交互程度。

因此，五档材质需要在相同设备、主题和系统设置下比较。先统一观察条件，后面的选择才有参考价值。

二、组件的位置和面积为什么会改变选择

了解五档材质的基本变化以后，下一步就要把它们放回实际页面。

同一档材质用在不同位置，带来的感受会明显不同。顶部悬浮栏通常覆盖标题、图片或滚动内容，底部操作栏承载按钮、页签和播放控制。菜单可能出现在任意背景上，半模态页面又会占据更大的画面面积。

这些差异决定了组件需要保留多少背景，也决定了前景内容需要多强的稳定性。

顶部悬浮区域可以先试 ULTRA_THIN

顶部悬浮组件需要和页面内容保持连续。ULTRA_THIN 能够保留更多背景信息，让滚动内容自然延伸到顶部。

顶部悬浮组件可以优先使用 ULTRA_THIN，并结合渐变模糊延展内容区域。背景中存在大量文字或高对比图案时，可以继续比较 THIN，重点检查标题与图标的可读性。

搜索框和底部操作栏可以先试 THIN

搜索框和底部操作栏既要保留页面背景，也要确保输入文字、按钮和图标足够清楚。

THIN 会比 ULTRA_THIN 多削弱一部分背景，组件自身仍然保持轻量。搜索框和底部悬浮区域都适合从这一档开始。

我在已有项目中通常先用 THIN 测试底部操作栏。按钮数量较多，或者背景图案比较复杂时，再向 REGULAR 调整。

普通悬浮卡片可以从 REGULAR 开始

REGULAR 位于五档样式中间，也是 ImmersiveMaterial 的默认样式。开发者没有填写 style 时，系统会采用这一档。

它适合作为比较基准。搜索框可以拿它和 THIN 比较，菜单可以拿它和 THICK 比较。这样比每次都测试五档更容易缩小范围。

菜单和临时浮层可以先试 THICK

菜单可能出现在图片、列表或视频上方，开发者很难提前控制它后面的背景。

THICK 能够明显降低背景干扰，让菜单文字和选项保持稳定。可能在任意位置弹出的临时组件也可以先从这一档开始。

菜单面积较小、背景又比较简单时，REGULAR 也可能已经够用，最终仍要结合真实页面判断。

弹窗和半模态页面可以先试 ULTRA_THICK

弹窗和半模态页面占据的面积更大，内部通常包含标题、正文、表单和操作按钮。

ULTRA_THICK 会进一步弱化背景，帮助当前内容形成清楚的层级。半模态页面和大面积弹出框也属于这一档的典型场景。

内容很少的小弹窗使用这一档后可能显得偏重。遇到这种情况，可以退回 THICK 再比较一次。

把组件位置和面积加入判断以后，五档样式就形成了更清楚的起始范围。

有了这张范围表，下一步就可以搭建一个变量足够少的页面，让五档样式在同一环境中直接对比。

三、怎样搭建一个可比较的最小页面

场景建议能够帮助开发者缩小范围，最终取值仍然需要通过运行结果判断。

为了让结果具有可比性，五张卡片必须使用相同条件。背景、尺寸、圆角或文字发生变化以后，页面差异就很难继续归因于 ImmersiveStyle。

当前示例统一使用下面这些条件：

• 五张卡片使用相同的宽度和高度。
• 五张卡片使用相同的圆角和文字层级。
• 五张卡片使用相同的三段彩色背景。
• 五个材质对象只修改 style。
• 页面使用相同的主题和沉浸光感强度。
• 截图使用相同的模拟器窗口尺寸。

ImmersiveMaterial 默认采用 REGULAR，材质赋色未设置，自动反色关闭，材质阴影开启，交互形变关闭，触点光感未设置。当前测试只覆盖 style，其余参数继续使用默认值。

这样处理以后，页面中最主要的变量就只剩材质厚度。

先创建五个材质对象

五个对象分别设置对应的 ImmersiveStyle。

private readonly ultraThinMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

   style: uiMaterial.ImmersiveStyle.ULTRA_THIN

 });

private readonly thinMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

   style: uiMaterial.ImmersiveStyle.THIN

 });

private readonly regularMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

   style: uiMaterial.ImmersiveStyle.REGULAR

 });

private readonly thickMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

   style: uiMaterial.ImmersiveStyle.THICK

 });

private readonly ultraThickMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

   style: uiMaterial.ImmersiveStyle.ULTRA_THICK

 });

这一轮没有开启 interactive 和 lightEffect。按压形变与触点光感会增加新的观察变量，后续验证交互参数时再打开更合适。

再让五张卡片共用同一套结构

五个材质对象通过同一个 @Builder 显示。

@Builder
private materialCard(

 title: string,

 scene: string,

 material: uiMaterial.Material

) {

 Stack() {
this.comparisonBackground()


   Column({ space: 7 }) {

     Text(title)

       .fontSize(18)

       .fontWeight(FontWeight.Bold)

       .fontColor('#17203A')


     Text(scene)

       .fontSize(13)

       .fontColor('#596179')

   }

   .width('88%')

   .height(96)

   .borderRadius(24)

   .justifyContent(FlexAlign.Center)

   .alignItems(HorizontalAlign.Center)

   .systemMaterial(material)

 }

 .width('100%')

 .height(142)

 .borderRadius(24)

 .clip(true)

}

五张卡片共用同一组背景和布局。后续需要调整测试条件时，只修改一个构建方法即可，也能避免卡片尺寸出现偏差。

页面完成以后，运行结果可以按照轻薄、常规和厚重三组逐步观察。

四、模拟器中的五档样式为什么看起来一样

按照最初的测试计划，我准备把五档样式分成三组观察：先比较 ULTRA_THIN 和 THIN，再把 REGULAR 作为中间参照，最后比较 THICK 和 ULTRA_THICK。

实际运行以后，页面给出的结果与预期并不一致。

五个 ImmersiveStyle 都能正常创建，五张卡片也都成功显示了沉浸材质，但它们在当前 HarmonyOS 7 模拟器中的视觉效果基本相同。背景颜色、文字透出程度、卡片通透度和整体层级都没有出现稳定、可辨认的差异。

当前示例在 HarmonyOS 7 模拟器中运行。五档材质对象都能正常创建并通过 systemMaterial 设置到组件上，说明接口调用和页面结构可以正常执行。不过，从实际截图来看，五张卡片没有呈现出清楚的厚度差异。

这个结果意味着，当前模拟器适合确认下面几项内容：

• ImmersiveStyle 的五个枚举值可以正常使用。
• ImmersiveMaterial 可以成功创建材质对象。
• 普通 ArkUI 组件可以通过 systemMaterial 显示沉浸材质。
• 五张卡片使用了相同的测试条件。

我先后使用了纯色分区、背景文字和更高密度的测试元素，模拟器中的五档结果仍然接近。结合这次运行情况，我们更适合把官方定义与模拟器结果分开记录：

这个结果虽然没有呈现预期中的五档变化，但它仍然有实际价值。开发者在模拟器中看到五档效果一致时，不需要立即怀疑枚举写错或材质对象创建失败。页面已经显示沉浸材质，说明基础调用链路已经接通；当前环境只是没有提供足够明确的视觉差异。

目前我的测试设备还没有相应的 HarmonyOS 7 实机测试权限，因此这一轮只能记录模拟器结果。具备开发者权限和支持设备时，建议使用同一份页面代码继续完成真机测试，并重点观察：

• 背景文字和细线的保留程度。
• 彩色区域交界处的柔化程度。
• 卡片高光、阴影和边框的变化。
• 大面积组件使用厚材质后的视觉重量。
• 强、均衡和弱三种系统设置下的差异。

看完五档对比以后，项目还需要结合具体组件做最后一轮选择。

我的习惯是先根据组件位置选出一档，然后向相邻两档各测试一次。这样既能控制工作量，也能避免第一印象直接决定最终结果。

搜索框可以比较三档

搜索框可以从 THIN 开始，然后比较：

ULTRA_THIN

THIN

REGULAR

背景比较简单时，ULTRA_THIN 可能已经足够。背景存在图片、列表文字或高对比图案时，REGULAR 的前景稳定性更值得关注。

底部操作栏需要看按钮数量

按钮数量较少时，可以先比较 ULTRA_THIN 和 THIN。

按钮、文字和状态较多时，可以继续加入 REGULAR。组件面积增大以后，过薄材质可能保留过多背景，进而影响图标和文字。

普通卡片可以把 REGULAR 当作起点

普通悬浮卡片可以先使用 REGULAR。

卡片主要用于简单操作时，可以向 THIN 调整。卡片包含较多说明文字和按钮时，可以向 THICK 调整。

菜单可以比较三档

菜单可以依次比较：

REGULAR

THICK

ULTRA_THICK

菜单背景简单、面积较小时，REGULAR 可能已经够用。菜单可能覆盖图片、视频或复杂页面时，THICK 通常更稳定。

弹窗和半模态页面需要关注整体重量

半模态页面可以从 ULTRA_THICK 开始，再与 THICK 比较。

内容较多时，超厚材质能够减少背景干扰。内容较少时，过厚材质可能让页面显得沉重，这时需要同时观察内容可读性和页面层级。

最终选择可以归纳为四步：

确认组件位置

↓

判断组件面积和信息密度

↓

选择一个起始样式

↓

与相邻样式进行同条件比较

这个过程不会一次解决所有页面，但它能够为每个组件留下清楚的选择依据。项目后续调整背景、字号或布局时，也可以继续沿用同样的测试方式。

总结

把五档材质放进同一个页面以后，我对 ImmersiveStyle 的理解也从枚举名称变成了更具体的页面判断。

ULTRA_THIN 会保留更多背景信息，适合顶部悬浮区域。THIN 在通透感和前景稳定性之间更容易取得平衡，搜索框和底部操作栏可以先从这一档开始。

REGULAR 是默认样式，也适合作为比较基准。THICK 能够减少复杂背景对内容的干扰，菜单和临时浮层可以优先测试。ULTRA_THICK 会进一步强化前后层级，大面积弹窗和半模态页面更容易从中受益。

对于已有项目，我更建议先从一个组件开始。搜索框比较三档，菜单比较三档，弹窗再比较两档。测试范围足够小，团队更容易看清差异，也能为后续调整留下依据。

模拟器暂时没有呈现出明显的五档差异，项目仍然可以根据官方定义和组件场景缩小选择范围。真正确定最终样式时，还需要把相邻档位放到支持相关能力的真机上继续比较。

这次运行让我确认了五档 ImmersiveStyle 的接口调用方式，也让我看到了模拟器验证的边界。五个材质对象都能正常显示，但当前模拟器没有呈现出稳定的视觉差异。因此，本文中的场景建议主要来自接口定义与设计指南，最终样式仍要通过真机运行结果确定。

完整代码

Main.ets

/**

* HarmonyOS 7 沉浸光感深度实战 03

*

* 验证环境：

* HarmonyOS SDK API 26

* HarmonyOS 7 模拟器

*/

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


@Entry

@Component

struct Main {

 @State private materialStateText: string =

   '当前应用尚未读取状态';


 @State private stateColor: ResourceColor =

   '#68708A';


 @State private stateDescription: string =

   '页面尚未读取应用级材质状态';


 /**

  * 五个材质对象只设置 style。

  * 其他参数继续使用 ImmersiveMaterial 的默认值。

  */
private readonly ultraThinMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

     style: uiMaterial.ImmersiveStyle.ULTRA_THIN

   });

private readonly thinMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

     style: uiMaterial.ImmersiveStyle.THIN

   });

private readonly regularMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

     style: uiMaterial.ImmersiveStyle.REGULAR

   });

private readonly thickMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

     style: uiMaterial.ImmersiveStyle.THICK

   });

private readonly ultraThickMaterial: uiMaterial.Material =
new uiMaterial.ImmersiveMaterial({

     style: uiMaterial.ImmersiveStyle.ULTRA_THICK

   });


 aboutToAppear(): void {
this.loadMaterialState();

 }


 /**

  * 读取当前应用的材质状态。

  * DISABLE 状态会关闭页面中的沉浸式系统材质。

  */
private loadMaterialState(): void {
const info: uiMaterial.MaterialInfo =

     uiMaterial.getMaterialInfo();

this.materialStateText =
this.getMaterialStateName(info.state);

this.stateColor =
this.getMaterialStateColor(info.state);

this.stateDescription =
this.getMaterialStateDescription(info.state);

 }

private getMaterialStateName(

   state: uiMaterial.MaterialState

 ): string {
switch (state) {
case uiMaterial.MaterialState.DEFAULT:
return 'DEFAULT';

case uiMaterial.MaterialState.ENABLE:
return 'ENABLE';

case uiMaterial.MaterialState.DISABLE:
return 'DISABLE';

default:
return `未知状态 ${state}`;

   }

 }

private getMaterialStateColor(

   state: uiMaterial.MaterialState

 ): ResourceColor {
switch (state) {
case uiMaterial.MaterialState.DEFAULT:
return '#5065E8';

case uiMaterial.MaterialState.ENABLE:
return '#1A8F5D';

case uiMaterial.MaterialState.DISABLE:
return '#C85A3A';

default:
return '#68708A';

   }

 }

private getMaterialStateDescription(

   state: uiMaterial.MaterialState

 ): string {
switch (state) {
case uiMaterial.MaterialState.DEFAULT:
return '当前状态允许普通组件主动设置沉浸材质。';

case uiMaterial.MaterialState.ENABLE:
return '当前状态允许页面比较五档沉浸材质。';

case uiMaterial.MaterialState.DISABLE:
return '当前状态会关闭页面中的全部沉浸材质。';

default:
return '当前状态没有对应说明。';

   }

 }


 @Builder
private sectionTitle(

   title: string,

   description: string

 ) {

   Column({ space: 4 }) {

     Text(title)

       .fontSize(22)

       .fontWeight(FontWeight.Bold)

       .fontColor('#11182C')

       .width('100%')


     Text(description)

       .fontSize(14)

       .fontColor('#68708A')

       .lineHeight(21)

       .width('100%')

   }

   .alignItems(HorizontalAlign.Start)

   .width('100%')

 }


 /**

  * 三段背景同时保留颜色、文字和分界线，

  * 方便观察不同样式对背景细节的处理。

  */

 @Builder
private comparisonBackground() {

   Row() {

     Column({ space: 4 }) {

       Text('01')

         .fontSize(24)

         .fontWeight(FontWeight.Bold)

         .fontColor('#DDE3FF')


       Text('BLUE')

         .fontSize(11)

         .fontColor('#DDE3FF')

     }

     .width('34%')

     .height('100%')

     .justifyContent(FlexAlign.Center)

     .alignItems(HorizontalAlign.Center)

     .backgroundColor('#4B62FF')


     Column({ space: 4 }) {

       Text('02')

         .fontSize(24)

         .fontWeight(FontWeight.Bold)

         .fontColor('#E5F5FF')


       Text('LIGHT')

         .fontSize(11)

         .fontColor('#E5F5FF')

     }

     .width('32%')

     .height('100%')

     .justifyContent(FlexAlign.Center)

     .alignItems(HorizontalAlign.Center)

     .backgroundColor('#59B7FF')


     Column({ space: 4 }) {

       Text('03')

         .fontSize(24)

         .fontWeight(FontWeight.Bold)

         .fontColor('#F0E5FF')


       Text('PURPLE')

         .fontSize(11)

         .fontColor('#F0E5FF')

     }

     .layoutWeight(1)

     .height('100%')

     .justifyContent(FlexAlign.Center)

     .alignItems(HorizontalAlign.Center)

     .backgroundColor('#A266FF')

   }

   .width('100%')

   .height('100%')

 }


 /**

  * 所有卡片共用相同的尺寸、圆角、背景和文字结构。

  */

 @Builder
private materialCard(

   title: string,

   scene: string,

   material: uiMaterial.Material

 ) {

   Stack() {
this.comparisonBackground()


     Column({ space: 7 }) {

       Text(title)

         .fontSize(18)

         .fontWeight(FontWeight.Bold)

         .fontColor('#17203A')


       Text(scene)

         .fontSize(13)

         .fontColor('#596179')

     }

     .width('88%')

     .height(96)

     .borderRadius(24)

     .justifyContent(FlexAlign.Center)

     .alignItems(HorizontalAlign.Center)

     .systemMaterial(material)

   }

   .width('100%')

   .height(142)

   .borderRadius(24)

   .clip(true)

 }


 @Builder
private stateCard() {

   Column({ space: 8 }) {

     Row({ space: 12 }) {

       Text('MaterialState')

         .width('38%')

         .fontSize(14)

         .fontColor('#68708A')


       Text(this.materialStateText)

         .layoutWeight(1)

         .fontSize(14)

         .fontWeight(FontWeight.Medium)

         .fontColor(this.stateColor)

         .textAlign(TextAlign.End)

         .maxLines(2)

     }

     .width('100%')

     .alignItems(VerticalAlign.Center)


     Divider()

       .color('#E8EBF2')


     Text(this.stateDescription)

       .fontSize(13)

       .fontColor('#68708A')

       .lineHeight(20)

       .width('100%')

   }

   .width('100%')

   .padding(16)

   .backgroundColor(Color.White)

   .borderRadius(20)

 }


 build() {

   Scroll() {

     Column({ space: 18 }) {

       Column({ space: 6 }) {

         Text('HarmonyOS 7 沉浸光感')

           .fontSize(28)

           .fontWeight(FontWeight.Bold)

           .fontColor('#11182C')

           .width('100%')


         Text('五档 ImmersiveStyle 对比')

           .fontSize(16)

           .fontColor('#68708A')

           .width('100%')

       }

       .alignItems(HorizontalAlign.Start)

       .width('100%')

this.sectionTitle(

         '当前应用状态',

         'DEFAULT 和 ENABLE 可以比较样式，DISABLE 会关闭全部材质。'

       )

this.stateCard()

this.sectionTitle(

         '统一条件对比',

         '五张卡片只修改 ImmersiveStyle，其余参数保持默认。'

       )

this.materialCard(

         'ULTRA_THIN',

         '顶部悬浮区域与轻量工具栏',
this.ultraThinMaterial

       )

this.materialCard(

         'THIN',

         '搜索框与底部操作栏',
this.thinMaterial

       )

this.materialCard(

         'REGULAR',

         '普通卡片与通用场景',
this.regularMaterial

       )

this.materialCard(

         'THICK',

         '菜单与临时浮层',
this.thickMaterial

       )

this.materialCard(

         'ULTRA_THICK',

         '弹窗与半模态页面',
this.ultraThickMaterial

       )


       Text(

         '请保持系统主题、沉浸光感强度和模拟器窗口尺寸一致。'

       )

         .fontSize(13)

         .fontColor('#747C92')

         .lineHeight(20)

         .padding({

           top: 4,

           bottom: 24

         })

         .width('100%')

     }

     .width('100%')

     .padding({

       left: 20,

       right: 20,

       top: 24,

       bottom: 24

     })

   }

   .width('100%')

   .height('100%')

   .backgroundColor('#F4F6FB')

 }

}