HarmonyOS 7 Immersive Light Effects: Choosing Between ArkUI and HDS Material APIs

Introduction

When adding immersive light effects to a HarmonyOS 7 application, developers encounter multiple material-related interfaces: uiMaterial, hdsMaterial, ImmersiveMaterial, ImmersiveStyle, MaterialLevel, systemMaterial, and systemMaterialEffect. These interfaces belong to two distinct API sets targeting different component categories.

The key distinction: standard ArkUI components use uiMaterial (from @kit.ArkUI, API 26.0.0+), while HDS spatial components like HdsNavigation, HdsTabs, and MiniBar use hdsMaterial (from @kit.UIDesignKit, version 6.1.0/23+). Both configure immersive materials but apply to different component types.

Two Interface Sets and Their Target Components

Standard ArkUI components — require module @kit.ArkUI; common invocation: ImmersiveMaterial with systemMaterial HDS spatial components — require module @kit.UIDesignKit; common invocation: MaterialType, MaterialLevel with component material properties

Standard components like Column, Row, search bars, and custom floating toolbars typically use uiMaterial. HDS components require checking HDS-specific material configuration via hdsMaterial.

Configuring Immersive Material for Standard ArkUI Components

Import the module: import { uiMaterial } from '@kit.ArkUI'; The uiMaterial module (API 26.0.0+, Stage model only) provides: MaterialState — records current app material switch state MaterialInfo — stores app material state and type getMaterialInfo() — reads material config from

module.json5

ImmersiveStyle

— selects material style for standard components ImmersiveOptions — sets color, shadow, invert, and interaction effects ImmersiveMaterial — creates immersive material object Material.empty — disables material effect for a specific component

Creating a THIN Material

The following code creates a thin material with press deformation and touch light feedback enabled:

private readonly thinMaterial: uiMaterial.Material = new uiMaterial.ImmersiveMaterial({  // THIN has strong transparency, suitable for search bars and small floating toolbars  style: uiMaterial.ImmersiveStyle.THIN,  // Enable system press deformation  interactive: true,  // Enable touch light effect with white color  lightEffect: {    color: Color.White  }});

ImmersiveMaterial

defaults to REGULAR style. interactive defaults to false, lightEffect defaults to unset. Explicit parameters make component behavior more observable.

Apply the material to a component via systemMaterial:

Column() {  Text('ArkUI Immersive Material')    .fontSize(20)    .fontWeight(FontWeight.Bold)}.width('100%').height(96).borderRadius(24).justifyContent(FlexAlign.Center).systemMaterial(this.thinMaterial)

ImmersiveMaterial

stores material parameters; systemMaterial assigns the material to the current component.

For existing projects, start with small-area components like search bars, image toolbars, or bottom action bars where material differences are easily visible. Avoid placing multiple materials on one page initially to limit debugging scope.

Selecting Material Type and Level for HDS Components

Import HDS material module:

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

hdsMaterial

provides MaterialType, MaterialLevel, and getSystemMaterialTypes().

MaterialType Enum

NONE

— No material ADAPTIVE — Adaptive, system chooses based on device performance IMMERSIVE — Immersive material

MaterialLevel Enum

EXQUISITE

— Exquisite level, higher performance cost GENTLE — Gentle level SMOOTH — Smooth level, lower runtime cost ADAPTIVE — System selects level based on device performance

HDS defaults to ADAPTIVE. When manually specifying a level, first call getSystemMaterialTypes() to confirm device-supported types. If IMMERSIVE is not returned, choose SMOOTH to reduce lag and overheating risk.

Querying Device-Supported HDS Material Types

const types: Array<hdsMaterial.MaterialType> = hdsMaterial.getSystemMaterialTypes();

getSystemMaterialTypes()

returns supported HDS material types. Handle type conversion and call exceptions; Beta environment failures may relate to SDK, system version, or emulator image — record errors with environment versions.

Do not confuse ImmersiveStyle (for standard ArkUI components) with MaterialLevel (for HDS component display levels); they are not interchangeable.

How App State, Device, and Component Parameters Interact

Final immersive light effect display depends on four condition categories:

System Settings

Users can choose immersive light intensity (Strong, Balanced, Weak) in system settings, affecting blur, highlights, shadows, and background rendering. Same code may show visual differences under different settings.

Device Capability

System adjusts material presentation per device capability tier (high, mid, low). High/mid-tier devices show more material details; low-tier may use background color, borders, and shadows for lighter effects. Tier classification is vendor-determined.

App-Level State

App sets material state in module.json5 via ohos.arkui.UIMaterial.state (requires targetAPIVersion ≥ 26.0.0, effective only in entry-type modules). Values: DEFAULT — App uses system default material rules ENABLE — Supported system components enable corresponding materials DISABLE — App disables immersive system materials

If ImmersiveMaterial is set but no material appears, first read MaterialState to confirm app state, then check component background, blur, and material parameters.

Component Parameters

Standard ArkUI components use ImmersiveStyle and ImmersiveOptions. HDS components use MaterialType, MaterialLevel, and respective component material properties.

Final result = System immersive light setting + Device capability + App-level MaterialState + Component material parameters.

Verifying Current Project

Create a verification page showing four items:

App current MaterialState — displays DEFAULT, ENABLE, or DISABLE App configured MaterialType — displays IMMERSIVE or other returned value

Device-supported HDS material types — displays NONE, IMMERSIVE, or other returned values

Standard ArkUI component display — card using THIN material

Reading App-Level Material Config

private loadArkUiMaterialInfo(): void {  const info: uiMaterial.MaterialInfo = uiMaterial.getMaterialInfo();  this.arkUiStateText = this.getArkUiStateName(info.state);  this.arkUiTypeText = this.getArkUiTypeName(info.type);}

getMaterialInfo()

reads module.json5 metadata config. MaterialInfo.state = current app material state; MaterialInfo.type = configured material type. App config determines if material is allowed; components still need ImmersiveMaterial for specific style and interaction params.

Querying HDS Material Types

private loadHdsMaterialTypes(): void {  try {    const types: Array<hdsMaterial.MaterialType> = hdsMaterial.getSystemMaterialTypes();    if (types.length === 0) {      this.hdsTypesText = '当前环境未返回 HDS 材质类型';      this.hdsSupportText = '未确认';      this.hdsSupportColor = '#D06C35';      return;    }    const names: string[] = [];    let supportsImmersiveMaterial: boolean = false;    for (let index: number = 0; index < types.length; index++) {      const type: hdsMaterial.MaterialType = types[index];      switch (type) {        case hdsMaterial.MaterialType.NONE:          names.push('NONE');          break;        case hdsMaterial.MaterialType.ADAPTIVE:          names.push('ADAPTIVE');          // ADAPTIVE defaults to immersive material          supportsImmersiveMaterial = true;          break;        case hdsMaterial.MaterialType.IMMERSIVE:          names.push('IMMERSIVE');          supportsImmersiveMaterial = true;          break;        default:          names.push(`UNKNOWN(${type})`);          break;      }    }    this.hdsTypesText = names.join('、');    if (supportsImmersiveMaterial) {      this.hdsSupportText = '支持';      this.hdsSupportColor = '#1A8F5D';    } else {      this.hdsSupportText = '未提供支持';      this.hdsSupportColor = '#D06C35';    }  } catch (error) {    const businessError = error as BusinessError;    this.hdsTypesText = `查询失败 ${businessError.code} ${businessError.message}`;    this.hdsSupportText = '查询失败';    this.hdsSupportColor = '#C53A3A';    this.hdsImmersiveSupported = false;  }}

Page retains full exception info. Emulator query failures may relate to SDK version, system image, or device capability; error codes help narrow debugging.

If interface returns IMMERSIVE, current environment provides HDS immersive material type. Actual display of HdsNavigation, HdsTabs, MiniBar still needs separate verification.

Checking Run Results

Example runs on HarmonyOS 7 emulator. App reads MaterialState = DEFAULT, ArkUI MaterialType = IMMERSIVE, standard component shows THIN material. getSystemMaterialTypes() returns empty array, so HDS immersive material marked as unconfirmed; further verification needed on capable physical devices. Query interface executed but emulator returned no specific HDS material types.

Interface Selection Guide for Existing Projects

Standard Card, Column, Row — uiMaterial.ImmersiveMaterial Search bars, small floating toolbars — Thinner ImmersiveStyle Popup, Menu, Tips, Sheet — Component's systemMaterial param

HdsNavigation, HdsTabs — hdsMaterial with HDS component material props

MiniBar, floating bottom navigation — HDS component provided material config

Read app material state — getMaterialInfo() Query HDS material support — getSystemMaterialTypes() Disable material for single component — uiMaterial.Material.empty Device only suits lightweight effects — HDS SMOOTH or standard background style

Start by modifying one search bar, image toolbar, or bottom action bar. Localized changes let developers clearly track each parameter's impact. For stable navigation, first assess HDS component page changes before evaluating modification scope. After this check, subsequent style comparisons and parameter experiments become easier to control.

Summary

Immersive light effects currently offer two main interface sets:

Standard ArkUI components: uiMaterial and systemMaterial HDS components: hdsMaterial with MaterialType and MaterialLevel controlling display

System settings, device capability, app state, and component parameters all participate in final display. Developers must record each condition to explain emulator vs. physical device differences.

After interface queries, modify module.json5 to sequentially verify default, enable, and disable states. These three states affect app material enablement scope and some system component default effects.

Complete Example: Main.ets

Full verification page implementation including imports, state management, material creation, app config reading, HDS type querying, UI builders for status items, section titles, ArkUI material card, and route cards explaining both interface scopes.

/** * HarmonyOS 7 Immersive Light Effects Deep Practice 01 * Verification Environment: * HarmonyOS SDK API 26 * HarmonyOS 7 Emulator */import { uiMaterial } from '@kit.ArkUI';import { hdsMaterial } from '@kit.UIDesignKit';import { BusinessError } from '@kit.BasicServicesKit';@Entry@Componentstruct Main {  @State private arkUiStateText: string = '当前应用尚未读取状态';  @State private arkUiTypeText: string = '当前应用尚未读取类型';  @State private hdsTypesText: string = '当前环境尚未查询 HDS 类型';  @State private hdsSupportText: string = '尚未查询';  @State private hdsSupportColor: ResourceColor = '#68708A';  /**   * Page creates material object only once.   *   Reduces duplicate object creation on page refresh.   */  private readonly thinMaterial: uiMaterial.Material =    new uiMaterial.ImmersiveMaterial({      // THIN retains strong transparency.      // Suitable for small floating components.      style: uiMaterial.ImmersiveStyle.THIN,      // interactive enables system press deformation.      interactive: true,      // lightEffect enables touch light feedback.      lightEffect: {        color: Color.White      }    });  aboutToAppear(): void {    this.loadArkUiMaterialInfo();    this.loadHdsMaterialTypes();  }  /**   * Reads app-level material config.   */  private loadArkUiMaterialInfo(): void {    const info: uiMaterial.MaterialInfo =      uiMaterial.getMaterialInfo();    this.arkUiStateText =      this.getArkUiStateName(info.state);    this.arkUiTypeText =      this.getArkUiTypeName(info.type);  }  /**   * Queries current environment supported HDS material types.   *   *   Returns empty array -> support status shows "unconfirmed".   *   Query exception -> page retains error code and message.   */  private loadHdsMaterialTypes(): void {    try {      const types: Array<hdsMaterial.MaterialType> =        hdsMaterial.getSystemMaterialTypes();      if (types.length === 0) {        this.hdsTypesText = '当前环境未返回 HDS 材质类型';        this.hdsSupportText = '未确认';        this.hdsSupportColor = '#D06C35';        return;      }      const names: string[] = [];      let supportsImmersiveMaterial: boolean = false;      for (let index: number = 0; index < types.length; index++) {        const type: hdsMaterial.MaterialType = types[index];        switch (type) {          case hdsMaterial.MaterialType.NONE:            names.push('NONE');            break;          case hdsMaterial.MaterialType.ADAPTIVE:            names.push('ADAPTIVE');            // ADAPTIVE defaults to immersive material.            supportsImmersiveMaterial = true;            break;          case hdsMaterial.MaterialType.IMMERSIVE:            names.push('IMMERSIVE');            supportsImmersiveMaterial = true;            break;          default:            names.push(`UNKNOWN(${type})`);            break;        }      }      this.hdsTypesText = names.join('、');      if (supportsImmersiveMaterial) {        this.hdsSupportText = '支持';        this.hdsSupportColor = '#1A8F5D';      } else {        this.hdsSupportText = '未提供支持';        this.hdsSupportColor = '#D06C35';      }    } catch (error) {      const businessError = error as BusinessError;      this.hdsTypesText = `查询失败 ${businessError.code} ${businessError.message}`;      this.hdsSupportText = '查询失败';      this.hdsSupportColor = '#C53A3A';    }  }  /**   * Converts MaterialState to page display text.   */  private getArkUiStateName(    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}`;    }  }  /**   * Converts ArkUI MaterialType to page display text.   */  private getArkUiTypeName(    type: uiMaterial.MaterialType  ): string {    switch (type) {      case uiMaterial.MaterialType.IMMERSIVE:        return 'IMMERSIVE';      default:        return `未知类型 ${type}`;    }  }  /**   * Displays a query result item.   *   Label uses fixed width, result uses remaining space,   *   reduces crowding of long texts.   */  @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)  }  /**   * Displays section title and description.   */  @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%')  }  /**   * Displays standard ArkUI component THIN material effect.   */  @Builder  private arkUiMaterialCard() {    Stack() {      // Dual-color background for observing material transparency.      Row() {        Column()          .width('42%')          .height('100%')          .backgroundColor('#4B62FF')        Column()          .layoutWeight(1)          .height('100%')          .backgroundColor('#9B5CFF')      }      .width('100%')      .height('100%')      Column({ space: 8 }) {        Text('ArkUI ImmersiveMaterial')          .fontSize(20)          .fontWeight(FontWeight.Bold)          .fontColor('#17203A')        Text('THIN · interactive · lightEffect')          .fontSize(13)          .fontColor('#4F5872')        Text('Press card to observe system feedback')          .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)  }  /**   * Displays scope of both material interfaces.   */  @Builder  private routeCard(    title: string,    moduleName: string,    route: string,    description: string  ) {    Column({ space: 8 }) {      Text(title)        .fontSize(17)        .fontWeight(FontWeight.Bold)        .fontColor('#17203A')        .width('100%')      Text(moduleName)        .fontSize(13)        .fontColor('#5065E8')        .width('100%')      Text(route)        .fontSize(13)        .fontColor('#343D59')        .width('100%')      Text(description)        .fontSize(13)        .fontColor('#747C92')        .lineHeight(20)        .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('ArkUI 与 HDS 接口查询页')            .fontSize(16)            .fontColor('#68708A')            .width('100%')        }        .alignItems(HorizontalAlign.Start)        .width('100%')        this.sectionTitle(          '当前应用配置',          '页面会读取应用级材质状态，并查询 HDS 材质类型。'        )        Column() {          this.statusItem(            'ArkUI MaterialState',            this.arkUiStateText          )          Divider()            .color('#E8EBF2')          this.statusItem(            'ArkUI MaterialType',            this.arkUiTypeText          )          Divider()            .color('#E8EBF2')          this.statusItem(            'HDS MaterialType',            this.hdsTypesText          )          Divider()            .color('#E8EBF2')          this.statusItem(            'HDS 沉浸材质',            this.hdsSupportText,            this.hdsSupportColor          )        }        .width('100%')        .padding({          left: 16,          right: 16,          top: 4,          bottom: 4        })        .backgroundColor(Color.White)        .borderRadius(20)        this.sectionTitle(          'ArkUI 普通组件',          '页面使用 ImmersiveMaterial 和 systemMaterial 设置组件材质。'        )        this.arkUiMaterialCard()        this.sectionTitle(          '两套接口',          '开发者可以先确认组件类型，再选择对应的材质接口。'        )        this.routeCard(          '普通 ArkUI 组件',          '@kit.ArkUI',          'uiMaterial → ImmersiveMaterial → systemMaterial',          '适用于普通容器、搜索框、工具栏和支持 systemMaterial 的浮层组件。'        )        this.routeCard(          'HDS 组件',          '@kit.UIDesignKit',          'hdsMaterial → MaterialType / MaterialLevel → systemMaterialEffect',          '适用于 HdsNavigation、HdsTabs、MiniBar 和悬浮导航。'        )        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')  }}