沉浸光感
====

从API版本26.0.0开始，新增沉浸光感。沉浸光感是ArkUI提供的一套高品质视觉与动效体系，通过沉浸式系统材质（[ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)）与空间动效的结合，为应用组件带来通透、精致的视觉表现。沉浸光感包含两部分能力：

*   沉浸式系统材质：通过影响组件的背景色[backgroundColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundcolor)、边框颜色[borderColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-border#bordercolor)、边框宽度[borderWidth](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-border#borderwidth)、阴影[shadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#shadow)和材质滤镜[materialFilter](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-filter-effect#materialfilter23)，让组件呈现具有层次感和通透感的视觉表现。
*   空间动效：为组件的弹出过程增添形变、流光等动态表现，使动画更加灵动流畅。

沉浸光感能够自动根据设备的算力档位和用户在系统设置中配置的沉浸光感强弱，自适应地调整沉浸式系统材质和动效的表现程度，使应用在不同档位的设备上都能呈现最佳效果。

沉浸光感开发过程中的常见问题及解决措施，请参见[沉浸光感常见问题](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-immersive-light-sense-faq)。

#### 沉浸式系统材质

沉浸式系统材质（[ImmersiveMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivematerial)）是ArkUI提供的一种新型材质对象，可以通过[systemMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#systemmaterial)接口、传入[ImmersiveOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)参数，设置组件的系统材质，设置后会自动影响组件的背景色、边框颜色、边框宽度、阴影和材质滤镜[materialFilter](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-filter-effect#materialfilter23)视觉效果。

沉浸式系统材质提供了五种材质样式[ImmersiveStyle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersivestyle)，从薄到厚分别为：

| 样式 | 说明 | 适用场景 |
| :-- | :-- | :-- |
| ULTRA\_THIN | 超薄样式，材质层具有很强的透明效果。 | 需要高度透明的背景，如浮动工具栏。 |
| THIN | 薄样式，材质层具有较强的透明效果。 | 需要较强透明度的场景，如搜索框。 |
| REGULAR | 常规样式，材质层厚度常规。 | 通用场景。 |
| THICK | 厚样式，模糊效果强。 | 需要较强模糊背景的场景，如菜单。 |
| ULTRA\_THICK | 超厚样式，模糊效果很强。 | 需要完全模糊背景的场景，如弹窗。 |

此外，沉浸式材质对象还支持配置以下属性：

*   [materialColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)：材质层赋色。对于高算力和中算力设备，若不设置该参数或该参数为undefined，不额外混合纯色效果；若设置该参数为有效颜色值，该参数会为材质滤镜[materialFilter](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-filter-effect#materialfilter23)再混合一层纯色效果，若该颜色为纯不透明的颜色，会遮挡材质滤镜效果。对于低算力设备，若不设置该参数或该参数为undefined，生效低算力设备材质自带的背景色效果；若设置该参数为有效颜色值，该参数作为背景色[backgroundColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundcolor)属性值。
*   [colorInvert](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)：设置了材质对象的节点的子树是否自动适配材质到背景色的反色。只有材质参数足够薄时才会自动反色。
*   [applyShadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)：是否添加材质的阴影效果。当该参数为true时，材质中的阴影效果固定生效，优先于[shadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#shadow)通用属性。当该参数为false时，[shadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#shadow)通用属性生效，材质的阴影效果不生效。
*   [interactive](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)：是否为设置材质的组件设置交互形变效果，启用后组件在按压时产生弹性形变。
*   [lightEffect](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)：是否为设置材质的组件设置光感交互反馈效果。

#### 亮点特征

*   **高端精致的视觉品质**：沉浸光感通过材质滤镜[materialFilter](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-filter-effect#materialfilter23)、高光、阴影等多层效果叠加，为组件带来远超纯色背景的高端视觉表现，让应用界面更具质感。
    
*   **自适应设备能力**：沉浸光感会根据设备算力自动调整效果表现，高档设备呈现完整效果，中低档设备自动降级，无需开发者手动适配，确保应用在各类设备上流畅运行。
    
*   **极简接入**：通过应用级开关即可一键开启沉浸光感，[Dialog](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-base-dialog-overview)、[菜单控制](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-menu)、[Chip](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-arkui-advanced-chip)等组件默认支持，无需额外代码改动即可获得高品质视觉效果。支持应用级开启的完整组件清单请参见[MaterialState](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#materialstate)。
    
*   **深浅色自适应**：沉浸式系统材质能够根据系统的深浅色模式自动展现不同的效果，无需开发者额外处理。
    
*   **智能反色保障可读性**：通过自动反色能力，当材质足够透明时，组件内的文字颜色会自动适配背景色，确保在任何场景下都具有良好的阅读体验。
    
*   **丰富的交互反馈**：支持交互形变（[interactive](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)）和光感交互反馈（[lightEffect](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)），让用户的每一次交互都有细腻的视觉回馈。
    

#### 开启沉浸光感

#### \[h2\]应用级开启

通过在[module.json5](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file)中配置metadata，可以全局控制应用内沉浸式系统材质的开启状态。其中，name字段需为"ohos.arkui.UIMaterial.state"，value字段可以为default、enable和disable。使用此能力前，需要确保应用的[targetAPIVersion](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-file)不低于26.0.0。该配置仅在entry类型的module中生效。

以下示例展示如何在module.json5中配置enable模式：

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

MaterialState提供应用级沉浸式系统材质配置的三种状态DEFAULT、ENABLE和DISABLE，即对应json5配置中的三个value枚举值。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/19/v3/-bDikhABR_ij748r2tfSdQ/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=947F8347C5D69EFC1DA682ED043B29D2B22648C410480C601E510A411A45E082)

支持应用级沉浸式系统材质的组件包括：[弹出框Dialog](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-base-dialog-overview)、[即时反馈（Toast）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-toast)、[AlphabetIndexer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-alphabet-indexer)、[ChipGroup](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-arkui-advanced-chipgroup)、[Chip](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-arkui-advanced-chip)、[Select](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-select)、[菜单控制](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-menu)、[Toggle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-toggle)、[SegmentButton](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-arkui-advanced-segmentbutton)、[SegmentButtonV2](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-arkui-advanced-segmentbuttonv2)、[Slider](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-slider)、[bindSheet](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#bindsheet)、[SelectionMenu](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ohos-arkui-advanced-selectionmenu)、[Text](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text)（设置[copyOption](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#copyoption9)后长按或双击触发的文本菜单）。

开发者可以通过[uiMaterial.getMaterialInfo()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#uimaterialgetmaterialinfo)获取当前应用的材质配置状态，并根据配置状态决定组件行为。

以下示例展示如何通过配置[MaterialState](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#materialstate)调整组件系统材质行为：当配置为ENABLE时，[Button](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-button)组件可主动设置沉浸式系统材质，[Select](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-select)组件会默认开启沉浸式系统材质；如需单独关闭某个组件的沉浸式系统材质，可设置[uiMaterial.Material.empty](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#empty)。

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

@Entry
@Component
struct MaterialInfoPage {
  private info: uiMaterial.MaterialInfo = uiMaterial.getMaterialInfo();

  build() {
    Column() {
      Text(\`MaterialState: ${this.info.state}\`)
        .fontSize(16)
        .margin({ bottom: 10 })
      Text(\`MaterialType: ${this.info.type}\`)
        .fontSize(16)
        .margin({ bottom: 20 })

      if (this.info.state === uiMaterial.MaterialState.ENABLE) {
        Button('使用沉浸式系统材质')
          .backgroundColor(Color.Transparent)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA\_THIN
          }))
          .fontColor(Color.Blue)
          .margin({ bottom: 10 })

        // Select组件默认开启沉浸式系统材质
        Select(\[{ value: '选项1' }, { value: '选项2' }\])
          .value('选择')
          .margin({ bottom: 10 })

        // 单独关闭Select的沉浸式系统材质
        Select(\[{ value: '选项1' }, { value: '选项2' }\])
          .value('选择（已关闭材质）')
          .systemMaterial(uiMaterial.Material.empty)
          // .menuSystemMaterial(uiMaterial.Material.empty)
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    // 请替换为实际资源文件
    .backgroundImage($r('app.media.img'))
    .backgroundImageSize(ImageSize.FILL)
  }
}

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a6/v3/8zUKLfz0QFGNSx9C0Af1pg/zh-cn_image_0000002664327741.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=E6BDC2D6B90D67C85D354F075D810B761B416739AEDD3FB87543F8CB0441975D)

#### \[h2\]组件级开启

除了应用级开关，开发者还可以在组件级别精细控制沉浸式系统材质的开启。根据组件类型的不同，设置方式分为通过通用属性设置和通过独有接口设置两类。

1.  通过通用属性设置。
    
    所有支持通用属性的组件，均支持通过[systemMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#systemmaterial)通用属性设置沉浸式系统材质。
    
    **Column组件示例**
    
    以下以Column组件作为示例，介绍如何通过通用属性开启沉浸式系统材质。
    
    import { uiMaterial } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct ColumnMaterialPage {
      build() {
        Column() {
          Column() {
            Text('沉浸光感')
          }
          .width(328)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA\_THIN,
          }))
        }
        .width('100%')
        .height('100%')
        .justifyContent(FlexAlign.Center)
        // 请替换为实际资源文件
        .backgroundImage($r('app.media.img'))
        .backgroundImageSize(ImageSize.FILL)
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c0/v3/eQVl9VfTQzeeC8J7S_-Y7g/zh-cn_image_0000002633848632.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=8EC3B7505CA540CBB5F9556F80760A6C39601D8E86E8EC11B678540B37924362)
    
    **Column交互形变示例**
    
    以下示例为[Column](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-column)组件同时设置ULTRA\_THIN样式和[interactive](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)交互形变效果，用户按压时组件会产生弹性形变，松手后自动恢复，增强交互的视觉反馈。
    
    import { uiMaterial } from '@kit.ArkUI'
    
    @Entry
    @Component
    struct ButtonInteractivePage {
      build() {
        Stack() {
          // 请替换为实际资源文件
          Image($r('app.media.img'))
            .width('100%')
            .height('100%')
          Column() {
            Column() {
              Text('Context')
            }
            .margin({ bottom: 100 })
            .width(248)
            .height(56)
            .borderRadius(28)
            .justifyContent(FlexAlign.Center)
            .alignItems(HorizontalAlign.Center)
            .systemMaterial(new uiMaterial.ImmersiveMaterial({
              style: uiMaterial.ImmersiveStyle.ULTRA\_THIN,
              interactive: true,
            }))
          }.height('100%').width('100%').justifyContent(FlexAlign.Center)
        }
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0d/v3/d_tLjtPsSY-46fM2peXbKw/zh-cn_image_0000002634008536.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=C223368E8ED8D2176C850D89A7535BC1A69EBB9891E3A7F213A4703007A70644)
    
    **光感交互反馈示例**
    
    以下示例为一组圆形Row组件同时开启[interactive](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)交互形变和[lightEffect](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)光感交互反馈，用户手指触摸组件时会产生流光跟随效果，按压时产生弹性形变。
    
    import { uiMaterial } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct LightEffectPage {
      @State itemsKey: number\[\] = \[0, 1, 2\];
      @State circleRadius: number = 40;
      @State spaceValue: number = 10;
      @State myMaterial: uiMaterial.Material = new uiMaterial.ImmersiveMaterial({
        style: uiMaterial.ImmersiveStyle.ULTRA\_THIN,
        interactive: true,
        lightEffect: { color: undefined },
      });
    
      build() {
        Column() {
          Row() {
            Text('标题')
              .flexGrow(2)
              .fontColor(Color.White)
            Row({ space: this.spaceValue }) {
              ForEach(this.itemsKey, (item: number, index: number) => {
                Row()
                  .width(this.circleRadius \* 2)
                  .height(this.circleRadius \* 2)
                  .borderRadius(this.circleRadius)
                  .systemMaterial(this.myMaterial)
              })
            }
          }
          .justifyContent(FlexAlign.End)
          .backgroundColor(Color.Black)
          .width('100%')
          .padding(20)
        }
        .height('100%')
        .width('100%')
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b2/v3/-UUvV9S6Q-iFIc3t0jIhaw/zh-cn_image_0000002664207683.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=E4DC005D162C949155AEDA03876514619C2A44186A5F122B2BCF4953E46F322D)
    
2.  通过组件独有接口设置。
    
    弹窗类组件支持通过设置自身的systemMaterial属性开启沉浸式系统材质。
    
    **Toast示例**
    
    以下示例通过showToast的[ShowToastOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-promptaction#showtoastoptions)参数设置THIN样式的沉浸式系统材质，Toast弹出时会呈现带有材质效果的半透明背景。
    
    import { PromptAction, uiMaterial } from '@kit.ArkUI';
    import { BusinessError } from '@kit.BasicServicesKit';
    
    @Entry
    @Component
    struct ToastMaterialPage {
      promptAction: PromptAction = this.getUIContext().getPromptAction();
    
      build() {
        Column() {
          Button('showToast')
            .position({ x: 125, y: 300 })
            .onClick(() => {
              try {
                this.promptAction.showToast({
                  message: 'Message Info',
                  duration: 2000,
                  // 控制是否设置系统材质
                  systemMaterial: new uiMaterial.ImmersiveMaterial({
                    style: uiMaterial.ImmersiveStyle.THIN
                  })
                });
              } catch (error) {
                let message = (error as BusinessError).message;
                let code = (error as BusinessError).code;
                console.error(\`showToast args error code is ${code}, message is ${message}\`);
              };
            })
        }
        .width('100%')
        .height('100%')
        // 请开发者替换为实际资源文件
        .backgroundImage($r('app.media.img'))
        .backgroundImageSize({ width: '100%', height: '100%' })
      }
    }
    
    未设置系统材质时：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/54/v3/GE3VN3h7R6SFMT16fyJptw/zh-cn_image_0000002664327743.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=4DFB145911588D0C3B764311561BBD3761EBCA64D0326DEC86D53676B9C6718D)
    
    设置系统材质后：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/de/v3/A-_5O2CFSceEHPuse8Sv-w/zh-cn_image_0000002633848634.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=2CF3754E2B3AC4C4428F82B0248842270DD5619F6073482507BE48A2559F9E7C)
    
    **Popup示例**
    
    以下示例通过bindPopup的[PopupOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-popup#popupoptions类型说明)参数设置THIN样式的沉浸式系统材质，气泡弹窗会呈现带有材质效果的半透明背景。
    
    import { uiMaterial } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct PopupMaterialPage {
      @State handlePopup: boolean = false;
    
      build() {
        Flex({ direction: FlexDirection.Column }) {
          Button('PopupOptions')
            .onClick(() => {
              this.handlePopup = !this.handlePopup
            })
            .bindPopup(this.handlePopup!!, {
              message: 'This is a popup with PopupOptions',
              placement: Placement.Top,
              // 控制是否设置系统材质
              systemMaterial: new uiMaterial.ImmersiveMaterial({
                style: uiMaterial.ImmersiveStyle.THIN
              })
            })
            .position({ x: 100, y: 300 })
        }.width('100%')
        // 请开发者替换为实际资源文件
        .backgroundImage($r('app.media.img'))
        .backgroundImageSize({ width: '100%', height: '100%' })
      }
    }
    
    未设置系统材质时：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/14/v3/hTg7jCCkQ1COej9tpDjndw/zh-cn_image_0000002634008538.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=AEAD4CA96D34B38520966D192B8B88E287CCB8056D582202ED93EDAD3560244C)
    
    设置系统材质后：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8c/v3/BmFGZnqfRb2VwXeRCccJsA/zh-cn_image_0000002664207685.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=D3C0B07D78D2061C14DD6CF864DB84102DA5DF74E600C91D4AFAC70EDBD70A8B)
    
    **Tips示例**
    
    以下示例通过bindTips的[TipsOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-tips#tipsoptions类型说明)参数设置THIN样式的沉浸式系统材质，悬浮提示会呈现带有材质效果的半透明背景。
    
    import { uiMaterial } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct TipsMaterialPage {
      build() {
        Flex({ direction: FlexDirection.Column }) {
          Button('Hover Tips')
            .bindTips('悬浮气泡测试', {
              // 控制是否设置系统材质
              systemMaterial: new uiMaterial.ImmersiveMaterial({
                style: uiMaterial.ImmersiveStyle.THIN
              })
            })
            .position({ x: 100, y: 300 })
        }.width('100%').padding({ top: 5 })
        // 请开发者替换为实际资源文件
        .backgroundImage($r('app.media.img'))
        .backgroundImageSize({ width: '100%', height: '100%' })
      }
    }
    
    未设置系统材质时：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/24/v3/OlBwdKRKT8q2IpwK8-PbvA/zh-cn_image_0000002664327745.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=FF895783C14F4109E1866FF9863807353BEDD99C1086A18E4DAE47C9A2238A17)
    
    设置系统材质后：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e1/v3/b8cBEomvQ8G9FkCdjnzOPQ/zh-cn_image_0000002633848636.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=25AC4884975753474A60C45303B8EC7B3A8D7783A567B83616813DF08C59482D)
    
    **bindSheet示例**
    
    以下示例通过bindSheet的[SheetOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-sheet-transition#sheetoptions)参数设置THICK样式的沉浸式系统材质，半模态页面会呈现带有模糊和材质效果的背景。
    
    import { uiMaterial } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct SheetMaterialPage {
      @State isShow: boolean = false;
      @State sheetHeight: number = 300;
      @State myMaterial: SystemUiMaterial | undefined = new uiMaterial.ImmersiveMaterial({
        style: uiMaterial.ImmersiveStyle.ULTRA\_THICK,
      });
    
      @Builder
      myBuilder() {
        Column({ space: 10 }) {
          Text('Text')
            .fontSize(20)
            .margin(10)
        }
        .width('100%')
        .height('100%')
      }
    
      build() {
        Stack() {
          // 请开发者替换为实际资源文件
          Image($r('app.media.startIcon'))
            .width('100%')
            .height('100%')
          Column() {
            Button('open Sheet')
              .onClick(() => {
                this.isShow = true;
              })
              .fontSize(20)
              .margin(10)
              .bindSheet($$this.isShow, this.myBuilder(), {
                height: this.sheetHeight,
                backgroundColor: Color.Transparent,
                systemMaterial: this.myMaterial // 从API版本26.0.0开始，新增systemMaterial属性
              })
          }
          .justifyContent(FlexAlign.Center)
          .width('100%')
          .height('100%')
        }
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ad/v3/RrlibehuS4eR0LREh_hDaQ/zh-cn_image_0000002634008540.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=B401DBFAD8374F630BA120758E95B3D75D071B8D5F57410F2A137C14966FCDE6)
    
    **menu示例**
    
    以下示例通过bindMenu的[MenuOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-menu#menuoptions10)参数设置THICK样式的沉浸式系统材质，弹出菜单会呈现带有材质效果的背景以及弹出动效。
    
    import { uiMaterial } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct MenuMaterialPage {
      @Builder
      MyMenu() {
        Menu() {
          MenuItem({ startIcon: $r('app.media.startIcon'), content: '菜单选项' })
          MenuItem({ startIcon: $r('app.media.startIcon'), content: '菜单选项' })
          MenuItem({ startIcon: $r('app.media.startIcon'), content: '菜单选项' })
        }
      }
    
      build() {
        Stack() {
          Button('bindMenu with THICK material')
            .bindMenu(this.MyMenu, {
              systemMaterial: new uiMaterial.ImmersiveMaterial({
                style: uiMaterial.ImmersiveStyle.THICK
              })
            })
        }
        .height('100%')
        .width('100%')
        // 请替换为实际资源文件
        .backgroundImage($r('app.media.img'))
        .backgroundImageSize(ImageSize.Cover)
      }
    }
    
    未设置系统材质时：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/37/v3/W09iaLeUSfKHsnHfxgU0ww/zh-cn_image_0000002664207687.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=5FF33224C01503ED5B37543BCDEC9B310C7E35CC6752E8CE5EEC1EE72797938A)
    
    设置系统材质后：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/9c/v3/ipaArdAvTACLqO1MvsxZ8w/zh-cn_image_0000002664327747.gif?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=2A98158279D029BC6D5B2188F907065F51079A39B59BC0195496873FB759D630)
    
3.  关闭组件的沉浸式系统材质。
    
    在ENABLE模式下，部分组件会默认开启沉浸式系统材质。如需单独关闭某个组件的沉浸式系统材质，可以设置[uiMaterial.Material.empty](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#empty)。
    
    import { uiMaterial } from '@kit.ArkUI';
    
    @Entry
    @Component
    struct CloseMaterialPage {
      build() {
        Column() {
          Text('关闭组件沉浸式系统材质')
            .fontSize(20)
            .fontWeight(FontWeight.Bold)
            .margin({ bottom: 30 })
    
          Text('默认开启沉浸式系统材质的Select：')
            .fontSize(16)
            .margin({ bottom: 10 })
    
          // Select组件默认开启沉浸式系统材质
          Select(\[{ value: '选项1' }, { value: '选项2' }\])
            .value('选择')
            .margin({ bottom: 30 })
    
          Text('单独关闭沉浸式系统材质的Select：')
            .fontSize(16)
            .margin({ bottom: 10 })
    
          // 单独关闭Select组件的沉浸式系统材质
          Select(\[{ value: '选项' }\])
            .value('选择')
            .systemMaterial(uiMaterial.Material.empty)
            // .menuSystemMaterial(uiMaterial.Material.empty)
        }
        .width('100%')
        .height('100%')
        .padding(20)
        .justifyContent(FlexAlign.Center)
      }
    }
    
    如果需要全局禁用所有组件的沉浸式系统材质，可在module.json5中将metadata的value设置为"disable"。
    

#### \[h2\]开启后的效果

沉浸式系统材质的效果会自动根据以下两个维度进行分档适配：

1.  **设备算力档位**：设备算力的高、中、低档由芯片决定。在高档和中档算力设备上，影响材质滤镜[materialFilter](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-filter-effect#materialfilter23)效果和阴影[shadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#shadow)效果。在低档算力设备上，影响背景色[backgroundColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-background#backgroundcolor)、边框颜色[borderColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-border#bordercolor)、边框宽度[borderWidth](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-border#borderwidth)、阴影[shadow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#shadow)效果。
2.  **系统沉浸光感配置**：用户可以在设备的系统设置中选择沉浸光感的强弱，支持强、弱和均衡三档配置。配置为"强"时，材质的光感最为明亮，材质层的模糊、高光、阴影等效果最为丰富，组件呈现最佳的通透感和质感；配置为"弱"时，效果最为精简，仅保留基础的背景色和边框表现；配置为"均衡"时，效果在视觉品质与性能之间取得平衡。

为组件设置了沉浸式系统材质后，在高档算力设备上，组件的弹出和消失过程会自动附带形变、流光等空间动效，使动画更加灵动流畅。动效无需开发者额外配置，由系统根据设备算力自动决定是否生效，在高档算力设备上自动生效，中低档算力设备不支持空间动效。

沉浸式系统材质在不同算力设备呈现的效果有差异，以下示例展示不同设备上材质样式的效果。

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

@Entry
@Component
struct AllStylesPage {
  build() {
    Column() {
      Stack() {
        // 请替换为实际资源文件
        Image($r('app.media.img'))
          .width('100%')
          .height('100%')

        Column({ space: 30 }) {
          Column() {
            Text('ULTRA\_THIN')
          }
          .width(328)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .alignItems(HorizontalAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA\_THIN,
          }))

          Column() {
            Text('THIN')
          }
          .width(328)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .alignItems(HorizontalAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.THIN,
          }))

          Column() {
            Text('REGULAR')
          }
          .width(328)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .alignItems(HorizontalAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.REGULAR,
          }))

          Column() {
            Text('THICK')
          }
          .width(328)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .alignItems(HorizontalAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.THICK,
          }))

          Column() {
            Text('ULTRA\_THICK')
          }
          .width(328)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .alignItems(HorizontalAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA\_THICK,
          }))
        }
      }
      .height('90%')
      .width('90%')
    }
    .height('100%')
    .width('100%')
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
  }
}

在低档算力设备上表现：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/98/v3/f8PmZ6TNTtWjxxWl88ux9A/zh-cn_image_0000002633848638.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=3F84D02038E235F9C10F082C843838620926926332CC84AB18F4EE8D684C998A)

在中档算力设备上表现：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/82/v3/JhTy3fBGReSsJIWVnqFyaA/zh-cn_image_0000002634008542.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=6D2A0DE0013206EF211757A118B3B8F4C692D02D9B2BDCE3A4DFF60846AF5DBF)

在高档算力设备上表现：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a6/v3/8Omr3XEnSGGVeLCsBfMsog/zh-cn_image_0000002664207689.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=56D6E0367B62375CD415AF7E36965E75DD6423957568628B25FEF0D0FA25675A)

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

@Entry
@Component
struct MenuMaterialPage {
  @Builder
  MyMenu() {
    Menu() {
      MenuItem({ startIcon: $r('app.media.startIcon'), content: '菜单选项' })
      MenuItem({ startIcon: $r('app.media.startIcon'), content: '菜单选项' })
      MenuItem({ startIcon: $r('app.media.startIcon'), content: '菜单选项' })
    }
  }

  build() {
    Stack() {
      Button('bindMenu with THICK material')
        .bindMenu(this.MyMenu, {
          systemMaterial: new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.THICK
          })
        })
    }
    .height('100%')
    .width('100%')
    // 请替换为实际资源文件
    .backgroundImage($r('app.media.img'))
    .backgroundImageSize(ImageSize.Cover)
  }
}

沉浸光感设置为强的效果：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b2/v3/UWaxicCVQDqwsOMfCMBwBA/zh-cn_image_0000002664327749.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=6FBD54BEB1E5A83DCAB2C7F9DE3B61018FF3A06EB7E601F693A5BACFD0AB8CED)

沉浸光感设置为弱的效果：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/57/v3/1VJcyK3pRUac3XbZ3ERMfA/zh-cn_image_0000002633848640.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=35941E65585CEE2F552C99CCBC02C786886401C2B2680F3BB50098002DE4C2BB)

沉浸光感设置为均衡的效果：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8c/v3/7DlDdwxoQ_Os9gfwhUt4RQ/zh-cn_image_0000002634008544.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=0C9FF269D1104C2EFBD348956A636C15A554B9CA91FC961B9D437D9FDC9F31AD)

#### 约束和限制

#### \[h2\]属性冲突

设置沉浸式系统材质后，会影响组件的显示效果，具体说明参见[沉浸式系统材质](#沉浸式系统材质)。对于通过通用属性[systemMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#systemmaterial)设置材质的场景，建议将[systemMaterial](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-image-effect#systemmaterial)放在其他样式属性之后设置，这样可以确保材质效果优先级正确；通过组件options参数设置材质时则无需关注设置顺序。

对于所有设置了沉浸式系统材质的组件，不建议同时设置背景色、背景模糊、阴影和边框样式。在DEFAULT模式下，Dialog、Toast等组件在未设置背景色、模糊参数和阴影参数时会默认开启沉浸式系统材质；如果开发者主动设置了这些属性，则沉浸式系统材质不会默认开启，需要开发者主动通过systemMaterial属性设置。

#### \[h2\]深浅色模式

沉浸式系统材质能够根据系统的深浅色模式自动适配，展现出不同的效果。在浅色模式下，材质呈现明亮通透的效果；在深色模式下，材质呈现沉稳深邃的效果。开发者无需为不同模式分别配置材质参数。

浅色模式下材质效果：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b7/v3/xdryim5oTeqnT0-bF72gPQ/zh-cn_image_0000002664207691.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=231DD38A93C2E60FF694F245E6588797988185C63F923CC7DCEED5BEC9478B7C)

深色模式下材质效果：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c5/v3/SCvMpIoJTYmS8JlMZmvEGQ/zh-cn_image_0000002664327751.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=9AA3DC2F380DF665AC5D79E75D7C7B15FC52CCBB3C073929FB8B0276280E07D6)

#### \[h2\]自动反色

当组件设置为透明度较高的材质（如ULTRA\_THIN或THIN）时，组件内的文字可能与背景色对比度不足，导致阅读体验不佳。此时可以开启[ImmersiveOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uimaterial#immersiveoptions)中的colorInvert自动反色功能。

开启colorInvert后，组件子节点中的文字颜色会自动适配材质到背景色的反色，确保文字始终可读。说明如下：

*   自动反色仅在材质足够薄时生效，材质样式为THIN或ULTRA\_THIN。
*   自动反色与系统沉浸光感的强弱配置相关，材质越薄、沉浸光感越强，越容易符合反色要求。
*   自动反色仅对通过资源接口设置的颜色值生效，包括Text组件的[fontColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#fontcolor)，Button组件的[fontColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-button#fontcolor)，SymbolGlyph组件的[fontColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-symbolglyph#fontcolor)，Image组件的[fillColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-image#fillcolor)，Search组件的[placeholderColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-search#placeholdercolor)、[fontColor](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-search#fontcolor10)、[searchIcon](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-search#searchicon10)中的图标颜色、[cancelButton](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-search#cancelbutton10)中的图标颜色、[caretStyle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-search#caretstyle10)中的光标颜色，TabContent组件的[tabBar](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-tabcontent#tabbar)属性使用[BottomTabBarStyle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-tabcontent#bottomtabbarstyle9)样式时其中的文本和图标颜色。

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

@Entry
@Component
struct ColorInvertPage {
  build() {
    Column() {
      Stack() {
        // 请替换为实际资源文件
        Image($r('app.media.img'))
          .width('100%')
          .height('100%')

        Column({ space: 20 }) {
          // 未开启自动反色，文字可能难以辨认
          Column() {
            Text('未开启反色')
              .fontColor(Color.White)
          }
          .width(280)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA\_THIN,
            colorInvert: false,
          }))

          // 开启自动反色，文字颜色自动适配背景
          Column() {
            Text('开启反色')
              .fontColor(Color.White)
          }
          .width(280)
          .height(56)
          .borderRadius(28)
          .justifyContent(FlexAlign.Center)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA\_THIN,
            colorInvert: true,
          }))
        }
      }
      .width('100%')
      .height('100%')
    }
    .width('100%')
    .height('100%')
  }
}

反色开启前后对比：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1c/v3/qc5hNEm4QWypx5JwFXyNVA/zh-cn_image_0000002633848642.png?HW-CC-KV=V1&HW-CC-Date=20260709T132305Z&HW-CC-Expire=86400&HW-CC-Sign=DD28F5CC51445BEECF21932BE095D2E2594F95E3BFE45825BA6AA349B53A3EB8)

#### 与相关Kit的关系

[UI Design Kit](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ui-design-introduction)同样提供了沉浸光感能力，但其适用范围与ArkUI存在差异：

*   UI Design Kit：支持HDS导航和HDS底部页签两个组件的沉浸光感能力，开发者可以通过[TitleBarStyleOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavigation#titlebarstyleoptions)或[HdsTabsFloatingStyle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdstabs#hdstabsfloatingstyle)的systemMaterialEffect设置沉浸光感视效，具体请参考[UI Design Kit](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ui-design-introduction)下的[沉浸光感](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ui-design-hds-component-material)。
    
*   ArkUI：支持Button、Column、Row等ArkUI组件设置沉浸光感视效，及自定义材质样式、交互形变、光感反馈等效果。支持的组件清单请参考[应用级开启](#应用级开启)和[组件级开启](#组件级开启)。
    

开发者可以根据实际需求选择，如果应用使用HDS导航和底部页签组件，可以直接通过UI Design Kit快速开启沉浸光感；如果需要为更多组件或自定义布局添加沉浸光感效果，则使用本文介绍的ArkUI沉浸光感能力。