【HarmonyOS 7 沉浸光感深度实战】 02 全局开关、MaterialState 与最小 Demo

文章目录

• • 前言
  • 一、先弄清三个状态分别管什么
  • • [DEFAULT 仍然允许主动设置材质](#DEFAULT 仍然允许主动设置材质)
    • [ENABLE 会扩大默认材质范围](#ENABLE 会扩大默认材质范围)
    • [DISABLE 会关闭整个应用的沉浸材质](#DISABLE 会关闭整个应用的沉浸材质)
  • 二、全局开关为什么要重新构建应用
  • 三、测试页面为什么要放这三个对象
  • • 先读取当前应用配置
    • 再放一块主动设置材质的卡片
    • [最后用两个 Select 检查系统默认行为](#最后用两个 Select 检查系统默认行为)
  • 四、三次运行应该怎样看结果
  • • 先确认页面状态
    • 再观察主动材质卡片
    • [然后对比两个 Select](#然后对比两个 Select)
    • 三种状态的运行结果
    • • [DEFAULT 状态](#DEFAULT 状态)
      • [ENABLE 状态](#ENABLE 状态)
      • [DISABLE 状态](#DISABLE 状态)
  • 五、已有项目怎样选择应用级状态
  • • [DEFAULT 更适合已有项目起步](#DEFAULT 更适合已有项目起步)
    • [ENABLE 适合集中检查系统组件](#ENABLE 适合集中检查系统组件)
    • [DISABLE 适合缩小排查范围](#DISABLE 适合缩小排查范围)
    • [Material.empty 适合处理个别组件](#Material.empty 适合处理个别组件)
  • 总结
  • 完整示例
  • • `module.json5`
    • `Main.ets`

前言

前面我们把 ArkUI 与 HDS 两套接口分开以后，沉浸光感的入口就已经比较清楚了。普通 ArkUI 组件通过 uiMaterial 设置材质，HDS 组件则使用 hdsMaterial 查询和配置材质能力。

接口选对以后，页面依然可能看不到预期效果。而这个问题经常来自应用级开关。

我第一次看到 DEFAULT、ENABLE 和 DISABLE 时，很自然地把 DEFAULT 理解成没有开启。继续核对接口说明后才发现，DEFAULT 仍然允许普通组件主动设置沉浸材质，部分系统组件也会按照默认规则显示材质。

这个差异会直接影响排查思路。组件已经调用了 systemMaterial，页面效果却没有变化时，只盯着组件代码通常会浪费不少时间。应用级状态、构建结果和当前安装包都需要一起检查。

本次验证继续使用 HarmonyOS SDK API 26 和 HarmonyOS 7 模拟器。三次测试共用同一份 Main.ets，每次只修改 module.json5 中的状态值，然后重新构建并安装应用。

一、先弄清三个状态分别管什么

MaterialState 从 API 26.0.0 开始提供。getMaterialInfo() 会读取 entry 模块中配置的 metadata，并返回当前应用的材质状态和材质类型。

三个状态控制的范围有所不同。

配置值	枚举值	页面中的主要表现
default	MaterialState.DEFAULT	系统按照默认规则处理部分组件，普通组件可以主动设置材质
enable	MaterialState.ENABLE	更多系统组件会自动使用材质，普通组件仍然可以主动设置材质
disable	MaterialState.DISABLE	应用中的沉浸式系统材质会被关闭，主动设置的材质也会停止生效

DEFAULT 仍然允许主动设置材质

大家最容易误判的就是 DEFAULT。

这个状态会保留系统默认规则，同时允许开发者通过 systemMaterial 给普通组件设置 ImmersiveMaterial。因此，一块主动设置材质的 Column 可以在 DEFAULT 状态下显示效果。

系统只会为特定组件提供默认材质。其他组件仍然需要主动设置。

ENABLE 会扩大默认材质范围

应用切换到 ENABLE 后，Select、Toggle、Slider、菜单等更多系统组件会按照系统规则使用沉浸材质。

这个状态还会影响现有样式。沉浸式系统材质生效以后，材质样式的优先级会高于组件原有的背景色、模糊、阴影和边框。已有项目切换到 ENABLE 后，需要重新检查这些属性。

我更建议把 ENABLE 当成一次页面检查任务。项目里的 Select、菜单和弹窗可能同时发生变化，直接提交到主分支容易遗漏可读性和层级问题。

DISABLE 会关闭整个应用的沉浸材质

DISABLE 会关闭应用中的沉浸式系统材质。普通组件已经设置的 ImmersiveMaterial 也会停止生效。

这个状态很适合排查问题。页面出现大面积显示异常时，可以临时切换到 DISABLE。如果异常随材质关闭而消失，后续排查就可以集中在材质、背景色、普通模糊和阴影上。

三种状态大家可以先记成下面这组关系：

DEFAULT
系统按照默认规则处理部分组件
普通组件可以主动设置材质

ENABLE
更多系统组件自动使用材质
普通组件也可以主动设置材质

DISABLE
应用关闭沉浸式系统材质
主动设置的材质同时失效

二、全局开关为什么要重新构建应用

应用级材质状态需要写在 entry 模块的 module.json5 中。配置名称固定为 ohos.arkui.UIMaterial.state，配置值可以填写 default、enable 或 disable。

这项 metadata 只有写在 entry 类型的 module 中才会生效。项目的目标 API 版本也需要达到 API 26。

下面的配置将应用状态设置为 enable：

{
  "name": "ohos.arkui.UIMaterial.state",
  "value": "enable"
}

完整配置需要放进 module 节点的 metadata 数组：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "metadata": [
      {
        "name": "ohos.arkui.UIMaterial.state",
        "value": "enable"
      }
    ]
  }
}

这个值会进入应用安装包，页面上的按钮无法直接修改它。每次切换状态以后，工程都需要重新构建并安装。

我建议三次测试都使用同一份页面代码。这样可以把变量控制在应用级状态上，后面比较截图时也更容易说明问题。

第一次构建
value = default

第二次构建
value = enable

第三次构建
value = disable

除了页面代码，下面几项条件也要保持一致：

• 三次测试使用同一个 HarmonyOS 7 模拟器。
• 三次测试使用相同的系统主题。
• 三次测试使用相同的沉浸光感系统设置。
• 三次测试保持相同的滚动位置和操作顺序。
• 每次测试前都确认新安装包已经覆盖旧版本。

最后一项很容易被忽略。module.json5 已经修改，模拟器中运行的应用却仍然来自旧安装包，页面就会继续显示上一次的状态。

三、测试页面为什么要放这三个对象

应用级状态读取成功后，页面还需要有足够明确的观察对象。

如果页面只显示一个状态文本，那么测试只能证明 getMaterialInfo() 读取到了配置。组件材质是否跟着变化，仍然没有得到验证。

因此，当前页面会同时放置状态信息、主动材质卡片和两个 Select。

页面内容	需要观察的问题
状态信息区域	页面读取到的 MaterialState 是否与配置一致
主动材质卡片	应用主动设置的 ImmersiveMaterial 是否生效
系统默认 Select	ENABLE 是否会让 Select 自动使用材质
关闭材质的 Select	Material.empty 是否会关闭控件和菜单材质

先读取当前应用配置

页面启动时调用 getMaterialInfo()：

private loadMaterialInfo(): void {
  const info: uiMaterial.MaterialInfo =
    uiMaterial.getMaterialInfo();

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

  this.materialTypeText =
    this.getMaterialTypeName(info.type);

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

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

MaterialInfo.state 表示应用当前采用的状态，MaterialInfo.type 只用于标识当前配置的材质类型。组件使用哪一档 ImmersiveStyle，仍然由组件自己的 ImmersiveMaterial 决定。

这里我会先看页面顶部的状态。顶部结果如果与 module.json5 不一致，下面的组件效果暂时没有分析价值，工程需要先确认构建和安装是否完成。

再放一块主动设置材质的卡片

三种状态会共用同一个 THIN 材质对象：

private readonly thinMaterial: uiMaterial.Material =
  new uiMaterial.ImmersiveMaterial({
    // THIN 适合小面积悬浮组件。
    style: uiMaterial.ImmersiveStyle.THIN,

    // 开启系统按压形变。
    interactive: true,

    // 开启触点光感。
    lightEffect: {
      color: Color.White
    }
  });

ImmersiveMaterial 的默认样式为 REGULAR，interactive 默认关闭，lightEffect 默认没有设置。当前示例主动填写这些参数，可以让按压和材质变化更容易观察。

页面通过 systemMaterial 把材质设置给普通 Column：

Column({ space: 8 }) {
  Text('主动设置 ImmersiveMaterial')
    .fontSize(19)
    .fontWeight(FontWeight.Bold)

  Text('THIN · interactive · lightEffect')
    .fontSize(13)
}
.width('88%')
.height(126)
.borderRadius(28)
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)
.systemMaterial(this.thinMaterial)

按照 MaterialState 的接口定义，这块卡片在 DEFAULT 和 ENABLE 状态下可以显示材质。应用切换到 DISABLE 后，系统会关闭这块卡片的材质。

最后用两个 Select 检查系统默认行为

第一个 Select 不设置材质属性：

Select([
  { value: '选项 A' },
  { value: '选项 B' }
])
.value('系统默认 Select')
.width('90%')

在 ENABLE 状态下，Select 会按照系统规则使用沉浸材质。DEFAULT 状态不会把 Select 纳入全局使能范围，因此这个控件通常保持普通显示。

第二个 Select 使用空材质：

Select([
  { value: '选项 A' },
  { value: '选项 B' }
])
.value('关闭材质的 Select')
.width('90%')
.systemMaterial(uiMaterial.Material.empty)
.menuSystemMaterial(uiMaterial.Material.empty)

Material.empty 可以在使能模式下关闭支持组件级材质接口的组件。Select 还需要通过 menuSystemMaterial(Material.empty) 关闭下拉菜单的材质。

我觉得这个对比比单独展示一块材质卡片更有用。它可以让开发者同时看到全局开关和局部关闭之间的关系，也能帮助已有项目判断哪些组件需要保留普通样式。

四、三次运行应该怎样看结果

页面完成后，我们需要分别使用 default、enable 和 disable 构建三次。

当前工程还没有生成三次模拟器运行截图，因此下表记录的是接口定义对应的预期结果。发布时仍要以实际页面返回值和截图为准。

观察对象	DEFAULT	ENABLE	DISABLE
页面读取到的状态	DEFAULT	ENABLE	DISABLE
主动设置材质的卡片	显示材质	显示材质	材质关闭
系统默认 Select	保持普通显示	自动显示材质	材质关闭
使用 Material.empty 的 Select	保持普通显示	控件与菜单关闭材质	材质关闭

先确认页面状态

页面顶部的 MaterialState 应当与 module.json5 中的配置一致。

配置已经改成 enable，页面仍然显示 DEFAULT 时，可以依次检查：

• metadata 是否写在 entry 类型的 module 中。
• 配置名称是否完整。
• 配置值是否使用小写。
• 工程是否重新构建。
• 模拟器中的应用是否已经更新。

完成这些检查后，再继续观察组件效果。这样可以避免把安装包问题误判成接口问题。

再观察主动材质卡片

DEFAULT 和 ENABLE 状态下，卡片应当保留材质效果。

切换到 DISABLE 后，内层面板的通透、模糊、阴影和高光应当消失。底层双色背景仍然保留，因此截图时需要重点观察内层面板。

然后对比两个 Select

ENABLE 状态最适合观察两个 Select 的差异。

系统默认 Select 会自动使用材质，另一个 Select 通过 Material.empty 保持普通显示。两个控件放在同一块彩色背景上以后，差异会更加清楚。

DEFAULT 状态下，两个 Select 的差异可能很小。这个结果符合状态定义，截图时无需刻意制造差异。

三种状态的运行结果

三次测试继续使用同一份 Main.ets，并保持模拟器、系统主题、窗口尺寸和页面位置一致。每次测试只修改 module.json5 中的 value，随后重新构建并安装应用。

这样的安排可以把页面变化集中到 MaterialState 上，也方便读者逐张对照运行结果。

DEFAULT 状态

第一轮测试将 module.json5 中的状态设置为 default。

{
  "name": "ohos.arkui.UIMaterial.state",
  "value": "default"
}

当前示例运行在 HarmonyOS 7 模拟器中。页面读取到的 MaterialState 为 DEFAULT，主动设置的 THIN 材质可以正常显示。系统默认 Select 没有因为应用级状态自动启用材质，使用 Material.empty 的 Select 也保持普通显示。

ENABLE 状态

第二轮测试将状态改成 enable。

{
  "name": "ohos.arkui.UIMaterial.state",
  "value": "enable"
}

重新构建并安装以后，页面顶部应当显示 ENABLE。主动材质卡片继续显示沉浸效果，系统默认 Select 会进入应用级材质的使能范围。

页面读取到的 MaterialState 为 ENABLE。主动设置的 THIN 材质仍然生效，系统默认 Select 开始使用沉浸材质。第二个 Select 同时设置了 systemMaterial(Material.empty) 和 menuSystemMaterial(Material.empty)，因此控件与下拉菜单继续使用普通样式。

ENABLE 影响的组件更多，所以这次测试还需要留意背景色、阴影、边框和文字对比度。已有页面使用了较多自定义样式时，这些细节需要逐项检查。

DISABLE 状态

第三轮测试将状态改成 disable。

{
  "name": "ohos.arkui.UIMaterial.state",
  "value": "disable"
}

应用重新安装后，页面顶部应当读取到 DISABLE。此时，应用中的沉浸式系统材质会被关闭，主动设置在卡片上的 ImmersiveMaterial 也会停止生效。

页面读取到的 MaterialState 为 DISABLE。主动设置的 THIN 材质已经关闭，两个 Select 也都使用普通样式。底层双色背景仍然保留，因此页面结构没有变化，变化主要集中在系统材质效果上。

DISABLE 很适合用来排查材质冲突。页面切换到这个状态后，如果显示异常随之消失，后续检查可以集中到 systemMaterial、背景色、普通模糊、阴影和前景颜色。

五、已有项目怎样选择应用级状态

三种状态对应不同的使用场景。项目可以根据当前改造范围选择。

DEFAULT 更适合已有项目起步

已有页面通常已经配置了背景色、阴影、菜单和弹窗。DEFAULT 对现有页面影响较小，开发者可以先给搜索框、悬浮工具栏或底部操作条设置材质。

我更倾向于把 DEFAULT 作为已有项目的起点。它可以让团队逐个检查组件，也方便记录哪些地方适合使用材质，哪些地方需要保留原来的样式。

ENABLE 适合集中检查系统组件

项目准备让更多系统组件使用沉浸材质时，可以切换到 ENABLE。

切换后建议重点检查：

• Select、Toggle 和 Slider 的背景是否正常。
• 菜单和下拉选项是否保持一致。
• 原有背景色是否被材质覆盖。
• 普通模糊是否与系统材质冲突。
• 阴影和边框是否符合页面层级。
• 深色模式下的文字是否清楚。

ENABLE 状态下，沉浸材质样式的优先级高于组件原有的背景色、模糊、阴影和边框。现有页面需要重新检查这些属性。

DISABLE 适合缩小排查范围

页面出现大面积显示异常时，可以临时把状态改成 DISABLE。

材质关闭后，如果页面恢复正常，后续排查可以集中在以下内容：

• systemMaterial
• 组件背景色
• 普通模糊
• 阴影和边框
• 前景文字颜色
• 浮层和菜单材质

这种方法很简单，但在 Beta 阶段很实用。它可以快速判断异常是否和沉浸材质有关。

Material.empty 适合处理个别组件

ENABLE 会让更多系统组件自动使用材质。个别组件出现可读性或背景冲突时，可以通过 Material.empty 单独关闭。

.systemMaterial(uiMaterial.Material.empty)

带有菜单的组件还需要处理菜单材质：

.systemMaterial(uiMaterial.Material.empty)
.menuSystemMaterial(uiMaterial.Material.empty)

组件需要先支持对应的组件级材质接口，Material.empty 才能生效。

总结

DEFAULT 适合已有项目逐个验证组件。它会保留系统默认规则，也允许应用主动设置材质。

ENABLE 适合集中检查 Select、Toggle、Slider、菜单等系统组件。这个状态会扩大材质影响范围，因此背景色、模糊、阴影和文字对比度都要重新检查。

DISABLE 适合排查页面异常。应用关闭材质以后，问题范围会明显缩小。

测试三种状态时，页面代码可以保持不变。每次只修改 module.json5 中的状态值，然后重新构建并安装应用。主动材质卡片、默认 Select 和关闭材质的 Select 可以把三种状态的差异集中展示出来。

对于已有项目，我更建议从 DEFAULT 开始。局部组件验证稳定以后，再切换到 ENABLE 检查系统组件。页面出现冲突时，可以使用 DISABLE 和 Material.empty 继续排查。

完成应用级状态验证以后，下一步可以在相同背景、尺寸和文字条件下比较五档 ImmersiveStyle。这五档样式会改变材质的通透度、模糊和视觉重量，也会直接影响工具栏、菜单和半模态页面的选择。

完整示例

module.json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "metadata": [
      {
        "name": "ohos.arkui.UIMaterial.state",
        "value": "enable"
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ]
      }
    ]
  }
}

Main.ets

/**
 * HarmonyOS 7 沉浸光感深度实战 02
 *
 * 验证环境：
 * HarmonyOS SDK API 26
 * HarmonyOS 7 模拟器
 */

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

@Entry
@Component
struct Main {
  @State private materialStateText: string =
    '当前应用尚未读取状态';

  @State private materialTypeText: string =
    '当前应用尚未读取类型';

  @State private stateDescription: string =
    '页面尚未读取应用级材质配置';

  @State private stateColor: ResourceColor =
    '#68708A';

  /**
   * 三种应用级状态共用同一个材质对象。
   */
  private readonly thinMaterial: uiMaterial.Material =
    new uiMaterial.ImmersiveMaterial({
      // THIN 适合小面积悬浮组件。
      style: uiMaterial.ImmersiveStyle.THIN,

      // 开启系统按压形变。
      interactive: true,

      // 开启触点光感。
      lightEffect: {
        color: Color.White
      }
    });

  aboutToAppear(): void {
    this.loadMaterialInfo();
  }

  /**
   * 读取 module.json5 中的应用级材质配置。
   */
  private loadMaterialInfo(): void {
    const info: uiMaterial.MaterialInfo =
      uiMaterial.getMaterialInfo();

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

    this.materialTypeText =
      this.getMaterialTypeName(info.type);

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

    this.stateColor =
      this.getMaterialStateColor(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 getMaterialTypeName(
    type: uiMaterial.MaterialType
  ): string {
    switch (type) {
      case uiMaterial.MaterialType.IMMERSIVE:
        return 'IMMERSIVE';

      default:
        return `未知类型 ${type}`;
    }
  }

  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 '当前状态没有对应说明。';
    }
  }

  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';
    }
  }

  @Builder
  private statusItem(
    label: string,
    value: string,
    valueColor: ResourceColor = '#18233F'
  ) {
    Row({ space: 12 }) {
      Text(label)
        .width('38%')
        .fontSize(14)
        .fontColor('#68708A')
        .maxLines(2)

      Text(value)
        .layoutWeight(1)
        .fontSize(14)
        .fontWeight(FontWeight.Medium)
        .fontColor(valueColor)
        .textAlign(TextAlign.End)
        .maxLines(3)
    }
    .width('100%')
    .padding({
      top: 12,
      bottom: 12
    })
    .alignItems(VerticalAlign.Center)
  }

  @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%')
  }

  /**
   * 主动设置 ImmersiveMaterial 的普通 ArkUI 组件。
   */
  @Builder
  private explicitMaterialCard() {
    Stack() {
      // 双色背景用于观察材质的透明与背景采样效果。
      Row() {
        Column()
          .width('42%')
          .height('100%')
          .backgroundColor('#4B62FF')

        Column()
          .layoutWeight(1)
          .height('100%')
          .backgroundColor('#9B5CFF')
      }
      .width('100%')
      .height('100%')

      Column({ space: 8 }) {
        Text('主动设置 ImmersiveMaterial')
          .fontSize(19)
          .fontWeight(FontWeight.Bold)
          .fontColor('#17203A')

        Text('THIN · interactive · lightEffect')
          .fontSize(13)
          .fontColor('#4F5872')

        Text('在 DISABLE 状态下观察材质变化')
          .fontSize(12)
          .fontColor('#68708A')
          .margin({ top: 8 })
      }
      .width('88%')
      .height(126)
      .borderRadius(28)
      .justifyContent(FlexAlign.Center)
      .alignItems(HorizontalAlign.Center)
      .systemMaterial(this.thinMaterial)
    }
    .width('100%')
    .height(190)
    .borderRadius(28)
    .clip(true)
  }

  /**
   * 对比系统默认 Select 和关闭材质的 Select。
   */
  @Builder
  private selectMaterialDemo() {
    Stack() {
      Row() {
        Column()
          .width('50%')
          .height('100%')
          .backgroundColor('#5B74FF')

        Column()
          .layoutWeight(1)
          .height('100%')
          .backgroundColor('#A266FF')
      }
      .width('100%')
      .height('100%')

      Column({ space: 16 }) {
        Text('Select 材质对比')
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.White)

        // ENABLE 状态下，Select 会按照系统规则使用沉浸材质。
        Select([
          { value: '选项 A' },
          { value: '选项 B' }
        ])
          .value('系统默认 Select')
          .width('90%')

        // 同时关闭 Select 本身和下拉菜单的材质。
        Select([
          { value: '选项 A' },
          { value: '选项 B' }
        ])
          .value('关闭材质的 Select')
          .width('90%')
          .systemMaterial(uiMaterial.Material.empty)
          .menuSystemMaterial(uiMaterial.Material.empty)
      }
      .width('88%')
      .height(220)
      .padding({
        top: 18,
        bottom: 18
      })
      .borderRadius(28)
      .justifyContent(FlexAlign.Center)
      .alignItems(HorizontalAlign.Center)
    }
    .width('100%')
    .height(270)
    .borderRadius(28)
    .clip(true)
  }

  @Builder
  private stateGuideCard() {
    Column({ space: 8 }) {
      Text('当前状态说明')
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
        .fontColor('#17203A')
        .width('100%')

      Text(this.stateDescription)
        .fontSize(14)
        .fontColor('#68708A')
        .lineHeight(21)
        .width('100%')
    }
    .width('100%')
    .padding(16)
    .backgroundColor(Color.White)
    .borderRadius(20)
  }

  build() {
    Scroll() {
      Column({ space: 20 }) {
        Column({ space: 6 }) {
          Text('HarmonyOS 7 沉浸光感')
            .fontSize(28)
            .fontWeight(FontWeight.Bold)
            .fontColor('#11182C')
            .width('100%')

          Text('MaterialState 与全局开关')
            .fontSize(16)
            .fontColor('#68708A')
            .width('100%')
        }
        .alignItems(HorizontalAlign.Start)
        .width('100%')

        this.sectionTitle(
          '当前应用状态',
          '页面会读取 module.json5 中的应用级材质配置。'
        )

        Column() {
          this.statusItem(
            'MaterialState',
            this.materialStateText,
            this.stateColor
          )

          Divider()
            .color('#E8EBF2')

          this.statusItem(
            'MaterialType',
            this.materialTypeText
          )
        }
        .width('100%')
        .padding({
          left: 16,
          right: 16,
          top: 4,
          bottom: 4
        })
        .backgroundColor(Color.White)
        .borderRadius(20)

        this.stateGuideCard()

        this.sectionTitle(
          '主动设置材质',
          '这块卡片用于观察应用级状态对显式材质的影响。'
        )

        this.explicitMaterialCard()

        this.sectionTitle(
          '系统默认与局部关闭',
          '两个 Select 用于比较系统默认材质和 Material.empty。'
        )

        this.selectMaterialDemo()

        Text(
          '修改 module.json5 后，请重新构建并安装工程，再观察页面状态与组件效果。'
        )
          .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')
  }
}