openharmony 鸿蒙 arkts-apis-uimaterial

2026-08-25 浏览 (1)

@ohos.arkui.uiMaterial (系统材质)

本模块提供系统材质的接口定义。不同的系统材质对应不同的UI效果，包括背景色backgroundColor、边框颜色borderColor、边框宽度borderWidth、阴影shadow效果、材质层滤镜效果。材质对象本身在不同算力的设备上表现存在差异，设备算力的高、中、低档由设备厂商决定，分档效果具体参考ImmersiveMaterial的描述。

起始版本： 26.0.0

导入模块

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

MaterialType

系统材质类型枚举。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称值说明
IMMERSIVE2沉浸式材质类型。仅用于MaterialInfo接口的type属性标识当前配置的材质类型，不映射到底层功能。实际材质效果通过ImmersiveMaterial类实现。

MaterialState

材质使能状态枚举，表示应用级沉浸式系统材质配置的状态。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称值说明
DEFAULT0默认模式。弹出框Dialog、即时反馈（Toast）、AlphabetIndexer在组件本身未设置背景颜色、模糊参数和阴影参数时默认开启沉浸式系统材质；Text设置copyOption后长按或双击触发的文本菜单默认开启沉浸式系统材质；其他组件由应用主动设置。
ENABLE1使能模式。除DEFAULT模式中启用沉浸式系统材质的四个组件以外，ChipGroup、Chip、Select、菜单控制、Toggle、SegmentButton、SegmentButtonV2、bindSheet组件默认开启沉浸式系统材质。此模式下，沉浸式系统材质样式生效的优先级高于组件本身设置的背景色、模糊、阴影和边框样式。每个组件可通过systemMaterial设置uiMaterial.Material.empty单独关闭；其他组件需开发者主动设置。
DISABLE2禁用模式。所有组件禁止开启沉浸式系统材质，即使主动为组件设置沉浸式系统材质参数也不会生效。

MaterialInfo

材质配置信息，包含材质使能状态和材质类型。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型只读可选说明
stateMaterialState否否材质使能状态配置。
typeMaterialType否否材质类型标识，表示当前配置对应的材质类型。该值仅用于类型标识，不映射到底层功能。

getMaterialInfo

getMaterialInfo(): MaterialInfo

获取当前应用的材质配置信息。返回的配置信息来自应用在module.json5中配置的metadata。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型说明
MaterialInfo返回当前应用的材质配置信息，包含材质使能状态和材质类型。

empty

static get empty(): Material

返回空材质对象，用于组件单独关闭沉浸式系统材质效果。使用方式为uiMaterial.Material.empty。

在enable模式下，可通过设置systemMaterial(uiMaterial.Material.empty)来单独关闭某个组件的沉浸式系统材质效果。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型说明
Material返回空材质对象，表示无材质效果。

ImmersiveStyle

沉浸式材质样式枚举。不同的材质样式对应不同的材质参数，主要包括材质的模糊程度、高光效果等。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称值说明
ULTRA_THIN0超薄样式。材质层超薄，具有很强的透明效果。
THIN1薄样式。材质层薄，具有较强的透明效果。
REGULAR2常规样式。材质层的厚度常规。
THICK3厚样式。模糊效果强。
ULTRA_THICK4超厚样式。模糊效果很强。

ImmersiveOptions

沉浸式材质参数。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型只读可选说明
styleImmersiveStyle否是材质样式。不同样式对应不同的材质参数，影响材质的厚度。
说明：该参数仅对高档和中档算力设备的显示效果生效。
默认值：ImmersiveStyle.REGULAR
materialColorResourceColor否是材质层赋色，该参数会为材质滤镜再混合一层纯色效果。该颜色需要带一定的透明度值，不能为纯不透明的颜色，否则会将材质滤镜效果完全遮挡。
说明：该参数仅对高档和中档算力设备的显示效果生效。
默认值：Color.Transparent
colorInvertboolean否是设置了材质对象的节点的子树是否自动适配材质到背景色的反色。
若为false，则不会自动反色。
若为true，则只有材质参数足够薄时才会自动反色。具体能反色的材质由系统定义，材质样式至少为THIN或ULTRA_THIN，且与设置应用的沉浸光感的强弱配置相关。材质越薄、沉浸光感越强，越容易符合反色材质的要求。
自动反色能力仅对部分属性接口设置特殊资源值时生效，生效的属性接口包括：Text组件的fontColor，Button组件的fontColor，SymbolGlyph组件的fontColor，Image组件的fillColor，Search组件的placeholderColor、fontColor、searchIcon中的图标颜色、cancelButton中的图标颜色、caretStyle中的光标颜色，TabContent组件的tabBar属性使用BottomTabBarStyle样式时其中的文本和图标颜色。
说明：该参数仅对高档和中档算力设备的显示效果生效。
默认值：false
applyShadowboolean否是是否添加材质的阴影效果。
当该参数为true时，材质中的阴影效果固定生效，优先于shadow通用属性。当该参数为false时，shadow通用属性生效，材质的阴影效果不生效。
说明：该参数仅对所有档位的算力设备的显示效果生效。
默认值：true

Material

UI侧的系统材质对象基类。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

卡片能力： 从API版本26.0.0开始，该接口支持在ArkTS卡片中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

ImmersiveMaterial

沉浸式材质类，继承自Material。

沉浸式材质根据设备算力有分档表现，设备算力的高、中、低档由设备厂商决定，定义在系统配置文件中。在高档和中档算力设备上，影响材质层滤镜效果和阴影shadow效果。在低档算力设备上，影响背景色backgroundColor、边框颜色borderColor、边框宽度borderWidth、阴影shadow效果。且同一材质的效果，会受到设置应用中沉浸光感配置项的影响，不同强弱程度的沉浸光感配置下，材质的参数和效果存在差异。

constructor

constructor(options?: ImmersiveOptions)

ImmersiveMaterial的构造函数。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
optionsImmersiveOptions否系统材质配置选项，包括材质样式、材质层赋色等。
默认值参考ImmersiveOptions接口各参数的默认值，即{style:ImmersiveStyle.REGULAR, materialColor:Color.Transparent, colorInvert:false, applyShadow:true}。

示例

示例1（设置沉浸式系统材质）

本示例介绍如何将沉浸式材质的ImmersiveMaterial对象通过systemMaterial属性设置给组件。

从API版本26.0.0开始，新增ImmersiveMaterial对象和systemMaterial属性。

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

@Entry
@Component
struct SystemMaterialPage {

  build() {
    Column() {
      Stack() {
        Image($r('app.media.bg1')) // $r('app.media.bg1')需要替换为开发者所需的图像资源文件
          .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)
  }
}

在低档算力设备上表现：

systemMaterial

在中档算力设备上表现：

systemMaterial

在高档算力设备上表现：

systemMaterial

示例2（获取材质配置信息并使用空材质关闭沉浸式系统材质）

本示例介绍如何通过getMaterialInfo获取当前应用的材质配置信息，并根据配置状态使用empty关闭特定组件的沉浸式系统材质效果。

从API版本26.0.0开始，新增getMaterialInfo方法和empty方法。

首先在module.json5文件中配置开关信息，需注意只有在entry类型的module中配置才会生效。

{
  "module": {
    // ···
    "type": "entry", // 需注意只有在entry类型的module中配置才会生效。
    // ···
    "metadata": [{
      "name": "ohos.arkui.UIMaterial.state",
      "value": "enable"
    }],
    // ···
  }
}

然后按照如下内容编写测试代码。

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('Enable UiMaterial')
          .backgroundColor(Color.Transparent)
          .systemMaterial(new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.ULTRA_THIN
          }))
          .fontColor(Color.Blue)
          .margin({ bottom: 10 })
        // Select组件默认开启沉浸式系统材质
        Select([
          {value: 'select item'}
        ]).value('select item')
        .margin({ bottom: 10 })
        // 单独关闭Select组件的沉浸式系统材质
        Select([
          {value: 'select item'}
        ]).value('select item')
        .systemMaterial(uiMaterial.Material.empty)
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    // $r('app.media.img')需要替换为开发者所需的图像资源文件
    .backgroundImage($r('app.media.img')).backgroundImageSize(ImageSize.FILL)
  }
}

在高档算力设备上表现：

systemMaterialState

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 arkts-apis-uicontext-contextmenucontroller

openharmony 鸿蒙 errorcode-canvas

openharmony 鸿蒙 capi-oh-nativexcomponent-native-xcomponent-oh-nativexcomponent

openharmony 鸿蒙 errorcode-bindSheet

openharmony 鸿蒙 js-apis-arkui-uiExtension-sys

openharmony 鸿蒙 capi-arkui-accessibility-arkui-accessibilityeventinfo

openharmony 鸿蒙 capi-arkui-rendernodeutils

openharmony 鸿蒙 capi-native-node-h-nodeattributetype-layoutcomponent

openharmony 鸿蒙 js-apis-arkui-node

openharmony 鸿蒙 capi-native-node-h

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/z7qxyHUe