沉浸光感不是一层毛玻璃贴图,是 ArkUI 在节点表面画的一块"系统材质"——它有档位、有算力分档、有生效范围,而且天生只认 ArkUI 节点,不认 Compose 的自绘像素。怎么把 API 26 的 ImmersiveMaterial 封装成一个 CMP(Compose Multiplatform)三方库、弹窗和菜单的壳怎么交给系统画、自绘 UI 又怎么跟系统材质对齐、跨端框架到底从哪条缝里用上系统材质——这篇文章用一个同时跑在鸿蒙模拟器和真机上的示例工程,把这三个问题一次讲透。

示例仓库:https://atomgit.com/dijun_520/cmp-ohos-immersive-material
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-KMP-CMP/kotlin/tree/main-2.2.21-OH
CMP 鸿蒙社区:https://atomgit.com/CPF-KMP-CMP


0. 环境与实测设备

项目版本
开发工具DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk)
系统 APIHarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0)
hvigor6.26.8(@ohos/hvigor-ohos-plugin)
KMP/CMP 工具链kotlin 2.2.21-1.2.0 / CMP 1.9.2-1.2.0 / skiko 0.9.22.2-1.2.0(CPF-KMP-CMP 社区发布版,ohosArm64 + ohosX64 双目标)
Node.js≥ 22.11.0
实测设备华为(nova 14)

1. “系统材质不就是毛玻璃吗”

鸿蒙 26 的沉浸光感嘛,不就是给弹窗和菜单加一层会透光的毛玻璃?跨端框架要做的,无非是把这层"玻璃"搬进 Compose 的画布里。

我一开始也以为它是一种画笔——拿到手、蘸上颜色、想画哪儿画哪儿。这个理解撑了我大概一个下午——直到我把示例里五档材质做成五个普通 Stack 切片,直接 .systemMaterial(new uiMaterial.ImmersiveMaterial(...)) 挂上去:

// hilog(真机,普通组件挂 ImmersiveMaterial)
W C03900/com.example.immersiveoverlays/Ace: Material inactive: out of scope.
Use component in navigation title bar or Tabbar.

五个切片,五条 inactive。翻开 @ohos.arkui.uiMaterial.d.ts(530 行)和 common.d.ts 里散落的声明,才看清楚它真正的形态:

// @ohos.arkui.uiMaterial.d.ts(去注释后的关键签名)
function getMaterialInfo(): MaterialInfo;            // 应用级开关,来自 module.json5 metadata
function getGlobalMaterialLevel(): MaterialLevel;     // EXQUISITE / GENTLE / SMOOTH
function isImmersiveMaterialSupported(): boolean;     // 设备支持性
class Material { static get empty(): Material; }      // 显式关闭
class ImmersiveMaterial extends Material {
  constructor(options?: ImmersiveOptions);            // style / materialColor / colorInvert
}                                                    // applyShadow / interactive / lightEffect

三个细节立刻推翻了我的朴素理解:

  1. 它不是画笔,是节点属性。systemMaterial(material) 挂在组件上,材质由系统在该节点的表面上渲染。画布没有"表面",自绘像素没有"节点",所以 Compose 画布里的东西天生挂不上——这不是封装问题,是管线问题。
  2. 它有生效范围。弹窗(AlertDialog、CustomDialog、ActionSheet)、菜单(Menu、SelectionMenu)、Sheet、Toast、Select 下拉、Slider、Toggle 这些"浮在内容上的表面"可以全页面生效;其他普通组件只认 Navigation 标题栏和底部悬浮 TabBar,别处设了也白搭——上面那五条 warn 就是证据。
  3. 它有算力分档。getGlobalMaterialLevel() 返回 EXQUISITE / GENTLE / SMOOTH 三档:高档走 filter(模糊 + 光感),低档直接退化成"底色 + 描边 + 阴影"。同一份代码,在模拟器上是玻璃,在真机上是白板。

所以这个题目的边界很清楚:在 CMP 里把沉浸光感做成三方库,弹窗/菜单这类表面交还 ArkUI 去承载(拿真材质),自绘内容用一份实测标定的参数表在 Skia 里做"形似"(对齐),并且两套结果必须能在真机上互相验证。

拆下来是三件事:

  • 探针:一次拿到 supported / state / level,决定整场降级策略;
  • Track A:把弹窗和菜单的"壳"交回 ArkUI,壳上挂真材质,内容照常是跨端框架的;
  • Track B:把材质翻译成 blur / tint / edge / sheen / shadow 五层参数,ArkTS 与 Kotlin 两侧同源实现,用真机做对齐标定。

2. 效果展示

模拟器首页:环境探针、四个入口卡片、五档对照与事件日志

这是 example 工程在模拟器(EXQUISITE 档)上的首页。这里每一行都不是装饰:

  • 顶部三个 pill 是探针结果:supported / state ENABLE / level EXQUISITE,来自 isImmersiveMaterialSupported() + getMaterialInfo() + getGlobalMaterialLevel() 三个 API 的一次合并调用;
  • 四个入口卡片对应两条轨道 × 两种表面:系统材质弹窗、自绘材质弹窗、系统材质菜单、自绘材质菜单;
  • "当前档位"那一行是标定表的实时输出:REGULAR 档在模拟器上是模糊 32.0vp、tint 0.23;
  • 底部事件日志每行对应一次 hilog 输出,真机上 hdc shell hilog -x | grep CMPMaterial 能看到同样的内容。

2.1 模拟器:玻璃是真的

点"系统材质弹窗"(REGULAR 档):

模拟器:系统材质弹窗,REGULAR 档,壳是半透明玻璃,背后色块透进来

弹窗的壳是系统画的:半透明、背后壁纸的暖色从右下角渗进来、圆角和投影都是系统材质的一部分。我一行背景色都没写——内容只有标题、正文和两个按钮,壳完全来自 systemMaterial(new uiMaterial.ImmersiveMaterial({ style: REGULAR, ... }))。

切到 ULTRA_THICK 档再开同一个弹窗:

模拟器:系统材质弹窗,ULTRA_THUCK 档,更厚、更白、阴影更重

同一段内容,壳明显变厚、变白、阴影变重。这就是"材质是档位化系统资源"的直接证据:ImmersiveStyle 五档(ULTRA_THIN → ULTRA_THICK)对应五组不同的系统材质参数,库内标定表的 blur 56vp / tint 0.44 就是从这一档对出来的。

自绘弹窗同一档位的样子:

模拟器:自绘材质弹窗(Track B),tokens 驱动,背后文字被模糊透出

标题后面那行"系统材质菜单"是画布上真实存在的文字,被自绘层的模糊压成了一团柔光——这就是 Track B 想达到的"形似"。它不是系统材质,是 backdropBlur + 着色 + sheen + 描边 + 投影 五层参数拼出来的,参数全部来自 tokensOf(ULTRA_THICK, EXQUISITE)。

菜单是同一套逻辑的另一种表面:

模拟器:自绘材质菜单,右上角浮层,四条目带分隔线

模拟器:系统材质菜单,bindMenu + MenuOptions.systemMaterial,壳由系统画

两张对比里我最想让你看的是壳的"厚薄感":自绘菜单的 sheen 从左上角斜切下来,系统菜单的壳则是系统按 THICK 档渲染的一整块材质。

2.2 真机:材质会"素颜"

同一个 example 装上真机(TLR-AL00,SMOOTH 档):

真机首页:level SMOOTH,模糊 0.0vp,五档切片全部退化为底色+描边

注意"当前档位"那行:REGULAR · 模糊 0.0vp · tint 0.57。和模拟器的 32.0vp / 0.23 对照,就是 SMOOTH 档的降级策略在起作用:系统不做 filter 了,自绘层也必须把模糊关掉、把着色加厚,否则两台设备上同一个组件一眼就不是一个东西。

真机上的系统材质弹窗:

真机:系统材质弹窗,SMOOTH 档,壳退化成白色底+描边+投影

白色的壳,没有任何玻璃感。一开始我以为是材质没生效,翻 hilog 才确认材质对象创建成功、弹窗正常打开(dialog opened id=169),只是低档设备的材质本来就是这个形态。系统在低算力设备上主动放弃 filter,是省电和帧率的取舍。

自绘弹窗和自绘菜单在真机上同样收敛:

真机:自绘材质弹窗,模糊关闭、着色加厚、sheen 保留

真机:自绘材质菜单,sheen 斜切可见,无模糊

系统材质菜单在真机上则收敛为一块白玻璃(THICK 档的白玻璃壳,条目齐全):

真机:系统材质菜单,SMOOTH 档,壳退化成白色底+描边

主动交代边界:模拟器上的玻璃感是真材质;真机上的素颜也是真材质——同一套 API、同一份 tokens 表,两种都是系统的诚实输出。真机的系统菜单(SMOOTH 档的白色壳)如上图。

2.3 真机上的 CMP 画布:Kotlin/Native 真编译真渲染

上面两节是 ArkTS 侧(Track A + Track B 的鸿蒙实现层)。这个库真正的跨端侧——cmp/ 里的 Kotlin/Compose 代码——这轮也编译进了真机:用 CPF-KMP-CMP 社区工具链把 cmp 模块编成 KLIB,再把 example/composeApp 链成 libkn.so,由壳工程通过 NAPI 加载,用 ComposeArkUIViewController 渲染出一整页 Compose UI。

ArkTS 实验室首页上多了一张入口卡片,点进去就是 CMP 画布:

真机:ArkTS 实验室首页,底部新增 CMP Compose 入口卡片

CMP Compose 页在真机(SMOOTH 档)上的首帧:

真机:CMP Compose 材质实验室,Kotlin/Native 渲染,探测状态与 token 面板

注意两个数字,它们证明了两条链路都通了:

  1. 状态行 supported=true state=ENABLE level=SMOOTH degraded=false——这不是 Kotlin 自己猜的,是 ArkTS 侧 CmpMaterialProbe.probe() 探测后经 NAPI 桥传进 Kotlin、注册进 CmpMaterialHostRegistry 的结果。跨端材质环境注入链路是活的。
  2. token 面板 blur=0.0 tint=0.57 edge=0.28 sheen=0.18——REGULAR 档在 SMOOTH 档位下的降级值:BASE_BLUR 32 × 0 = 0,BASE_TINT_ALPHA 0.23 + 0.34 = 0.57。

CMP 画布里的自绘弹窗浮层:

真机:CMP 画布内的自绘弹窗,遮罩 + token 驱动材质卡

这个弹窗不是系统弹窗——整层(蒙层、材质卡、按钮)都画在 Compose 场景树里,是纯 Kotlin/Skia 输出。它的壳参数来自 rememberMaterialTokens(),也就是 ArkTS 注入的同一份档位数据驱动的同一张标定表。

3. 原理:系统材质到底替你画了什么

先给全文最重要的模型判断:沉浸光感 = 一块"档位化的系统材质" + 一套"节点级挂载规则"。 材质对象(ImmersiveMaterial)只是参数包,真正的渲染在 ArkUI 渲染管线里;挂载规则决定了哪些表面能用、哪些挂了等于白挂。

把系统的入口和回调整理成表:

接口/配置方向作用
uiMaterial.isImmersiveMaterialSupported()应用 → 系统设备是否支持 ImmersiveMaterial
uiMaterial.getMaterialInfo()应用 → 系统应用级开关(DEFAULT/ENABLE/DISABLE),读 entry 模块 metadata
uiMaterial.getGlobalMaterialLevel()应用 → 系统设备算力档位,决定材质形态
module.json5 → metadata → ohos.arkui.UIMaterial.state应用 → 系统应用级开关配置,仅 entry 模块生效
.systemMaterial(material)应用 → 节点组件级挂载,优先级高于应用级开关
Material.empty应用 → 节点显式关闭某个组件的材质(与 undefined 语义不同)
ImmersiveOptions.lightEffect / interactive应用 → 材质光感反馈颜色 / 按压形变

两个细节决定了后面所有的设计:

  1. 生效范围是白名单制的。弹窗类(AlertDialog、CustomDialog、ActionSheet)、菜单类(Menu、SelectionMenu)、Sheet、Toast、Select、Slider、Toggle 全页面生效;Navigation 标题栏和底部悬浮 TabBar 走专门接口;其余普通组件只在部分场景生效。我们实测的 out of scope 就是这条规则的运行时证据。
  2. 算力档位决定材质形态。EXQUISITE/GENTLE 档走材质层 filter(模糊 + 着色 + 光感),SMOOTH 档直接退化为 backgroundColor/border/shadow 的静态组合。

由此推出跨端框架的处境,也是本库全部设计的起点:

跨端框架想要的系统给的差距
给自绘像素加材质材质只能挂在 ArkUI 节点上管线不通,参数也进不去
弹窗/菜单用系统材质浮层表面全页面生效壳必须交回 ArkUI 承载
多设备形态一致算力分档自动退化自绘必须拿到档位信息并同步退化

所以跨端框架只有两条路,中间那条"往自绘画布上挂 systemMaterial"是不存在的:

  • Track A(宿主材质):弹窗、菜单的壳交回 ArkUI——用 openCustomDialog / bindMenu 的 systemMaterial 选项挂真材质,内容(跨端框架的 UI)作为弹窗主体放进去。拿到的模糊、光感、形变都是真的。
  • Track B(自绘对齐):内容必须留在画布里时,把材质翻译成 blur / tint / edge / sheen / shadow 五层参数,在自绘渲染器里复现。参数表必须按 style × level 二维展开,因为系统会按算力退化,自绘不同步退化就是"两台设备两张皮"。

库的产出,就是把这两条路工程化,并且让它们共用同一份标定数据。

4. 工程怎么搭

cmp-ohos-immersive-material/
├── harmony/cmp_immersive_material/          # ArkTS 实现层(HAR)
│   └── src/main/ets/
│       ├── material/CmpMaterialTokens.ets   # 标定表 + tokens 模型
│       ├── material/CmpMaterialProbe.ets    # 探针 + 材质工厂
│       ├── components/CmpImmersiveSurface.ets   # Track B:自绘材质面
│       ├── components/CmpImmersiveDialog.ets    # 弹窗锚组件(A/B 双轨)
│       ├── components/CmpImmersiveMenu.ets      # 菜单(A/B 双轨)
│       └── utils/CmpLogger.ets
├── cmp/                                     # CMP Kotlin 库(KMP)
│   ├── build.gradle.kts                     # KMP + Compose 插件,ohosArm64/ohosX64
│   ├── src/commonMain/.../CmpMaterial.kt    # 模型 / 宿主接口 / expect
│   ├── src/commonMain/.../CmpImmersiveBackdrop.kt   # Compose 自绘材质 + 静态标定表
│   ├── src/commonMain/.../CmpOverlays.kt            # Compose 弹窗 / 菜单
│   └── src/ohosMain/.../
│       ├── CmpMaterialPlatform.ohos.kt      # actual:宿主注入
│       └── CmpMaterialHostNapi.kt           # NAPI 桥绑定实现(读 3 个字符串 → 注册表)
├── example/composeApp/                      # CMP 应用模块(链成 libkn.so)
│   ├── build.gradle.kts                     # sharedLib "kn" + publish 任务同步产物
│   ├── src/commonMain/.../MaterialLabApp.kt # CMP 材质实验室(Compose UI)
│   └── src/ohosMain/.../MainArkUIViewController.kt  # @CName 导出包装
└── example/harmony/                         # 真机宿主(含 module.json5 开关 + cpp/napi_init.cpp)

gradle 侧的基建跟着社区工具链走:根工程 settings.gradle.kts 里先挂 m2-mirror 本地镜像(kotlin-native-prebuilt 这类大构件预下载在里面),再挂 CPF 公网仓兜底;gradle/libs.versions.toml 锁 kotlin 2.2.21-1.2.0 / CMP 1.9.2-1.2.0;composeApp 用 binaries.sharedLib { baseName = "kn" } 链成鸿蒙动态库,构建完 publishDebugBinariesToHarmonyApp 任务把 libkn.so / libkn_api.h 拷进壳工程对应目录。

工程按"一套数据、两个渲染器、一个验证宿主"来切:

  • CmpMaterialTokens(ArkTS)和 CmpMaterialTokens(Kotlin)字段一一对应,数值表两边各存一份、改动必须同步——它们之间只传纯数据,不传 uiMaterial.Material 对象本身;
  • ArkTS 侧是真机验证的实现层(HAR),CMP 侧是 Compose API 面;
  • example 宿主同时承担"演示"和"标定"两个职责。

最小接入只有三步。第一步,entry 模块的 module.json5 打开应用级开关:

// example/harmony/entry/src/main/module.json5(节选)
"metadata": [
  {
    // 应用级沉浸光感开关:default / enable / disable,仅 entry 类型 module 生效
    "name": "ohos.arkui.UIMaterial.state",
    "value": "enable"
  }
]

第二步,启动时探一次环境:

// example/harmony/entry/src/main/ets/entryability/EntryAbility.ets(节选)
windowStage.loadContent('pages/Index', (err: BusinessError) => {
  // 页面起来之后立刻探一次材质环境,结果会打进 hilog
  CmpMaterialProbe.probe(true);
});

第三步,页面里挂一个零尺寸锚组件,随时打开双轨弹窗:

// example/harmony/entry/src/main/ets/pages/Index.ets(节选)
private dialogHost: CmpImmersiveDialogController = new CmpImmersiveDialogController();

build() {
  Stack() {
    // ...页面内容...
    CmpImmersiveDialogAnchor({ controller: this.dialogHost })
  }
}

private openDialog(useSystemMaterial: boolean): void {
  const spec: CmpDialogSpec = defaultDialogSpec(this.style, this.env.level, useSystemMaterial);
  this.dialogHost.show(spec, (): void => { /* 主操作 */ }, (): void => { /* 关闭 */ });
}

KMP 侧的 cmp/ 模块用社区工具链编译(版本见第 0 节),ArkTS 侧启动时把探针结果和 tokens 经互操作通道注入 Kotlin:

// 宿主注入(鸿蒙入口里执行一次)
CmpMaterialHostRegistry.install(object : CmpMaterialHost {
    override fun probeEnvironment(): CmpMaterialEnvironment = /* 来自 ArkTS probe 结果 */
    override fun tokensOf(style: CmpMaterialStyle, dark: Boolean) = /* 来自 ArkTS 标定表 */
})

通道里传的是纯数据(Record/JSON),不传材质对象——uiMaterial.Material 只能活在 ArkUI 语境里,跨语言传递没有意义,这也是 Track A/Track B 分轨的根本原因。

5. 把代码讲透

5.1 探针:三个 API 决定整场降级策略

探针是库的第一道工序,一次合并三个系统调用:

// harmony/cmp_immersive_material/src/main/ets/material/CmpMaterialProbe.ets - doProbe()(节选)
try {
  supported = uiMaterial.isImmersiveMaterialSupported();
} catch (e) {
  degraded = true;                       // API 不可用:整场走自绘
  reason = `isImmersiveMaterialSupported 不可用: ${(e as BusinessError).message}`;
}
try {
  const info: uiMaterial.MaterialInfo = uiMaterial.getMaterialInfo();
  state = info.state === uiMaterial.MaterialState.ENABLE ? STATE_ENABLE :
    (info.state === uiMaterial.MaterialState.DISABLE ? STATE_DISABLE : STATE_DEFAULT);
} catch (e) { /* 同上,降级 */ }
try {
  const lv: uiMaterial.MaterialLevel = uiMaterial.getGlobalMaterialLevel();
  level = lv === uiMaterial.MaterialLevel.EXQUISITE ? CmpMaterialLevel.EXQUISITE :
    (lv === uiMaterial.MaterialLevel.GENTLE ? CmpMaterialLevel.GENTLE : CmpMaterialLevel.SMOOTH);
} catch (e) { /* 同上,降级 */ }

真机上这份日志是后续所有行为的总开关:

// hilog(真机,TLR-AL00)
I A0C0DE/.../CMPMaterial: probe supported=true state=ENABLE level=SMOOTH degraded=false
// hilog(模拟器,EXQUISITE)
I A0C0DE/.../CMPMaterial: probe supported=true state=ENABLE level=EXQUISITE degraded=false

细节值得单独说:三个调用任何一个抛错,探针都不放弃,而是把 degraded=true 和原因记下来继续走——材质不可用的时候,自绘轨道必须能独立撑起整个 UI,这是跨端库的基本修养。

5.2 标定表:把"玻璃感"翻译成五个数

Track B 的核心资产是一张 5 档 × 3 档的参数表:

// harmony/cmp_immersive_material/src/main/ets/material/CmpMaterialTokens.ets(节选)
const BASE_BLUR: number[] = [14, 22, 32, 44, 56];           // 五档模糊半径(vp)
const BASE_TINT_ALPHA: number[] = [0.08, 0.15, 0.23, 0.33, 0.44];
const BASE_EDGE_ALPHA: number[] = [0.20, 0.24, 0.28, 0.32, 0.36];
const BASE_SHEEN_ALPHA: number[] = [0.10, 0.14, 0.18, 0.22, 0.26];
const BASE_SHADOW_BLUR: number[] = [14, 18, 24, 30, 36];
const BASE_SHADOW_ALPHA: number[] = [0.10, 0.12, 0.14, 0.16, 0.18];

function levelBlurScale(level: CmpMaterialLevel): number {
  switch (level) {
    case CmpMaterialLevel.EXQUISITE: return 1;
    case CmpMaterialLevel.GENTLE: return 0.78;
    // 低算力设备上系统不做 filter,只给底色 + 描边 + 阴影,
    // 自绘也必须把模糊关掉,否则两边一眼就不是一个东西。
    case CmpMaterialLevel.SMOOTH: return 0;
    default: return 1;
  }
}

function levelTintBoost(level: CmpMaterialLevel): number {
  switch (level) {
    case CmpMaterialLevel.EXQUISITE: return 0;
    case CmpMaterialLevel.GENTLE: return 0.06;
    case CmpMaterialLevel.SMOOTH: return 0.34;   // 模糊关了,着色补厚
    default: return 0;
  }
}

这组数字不是拍脑袋:拿真机系统材质当标尺,用 example 里的五档对照台逐档调出来,再用弹窗在模拟器和真机上双向复核。复核的证据就是第 2 节那两行"当前档位"输出:

设备档位REGULAR 档实测输出
模拟器(EXQUISITE)REGULAR模糊 32.0vp · tint 0.23 · edge 0.28
真机(SMOOTH)REGULAR模糊 0.0vp · tint 0.57 · edge 0.28

blur 归零、tint 从 0.23 抬到 0.57——退化不是"少了几层",是"换了一套画法"。

5.3 Track A:弹窗的壳怎么交回系统

弹窗是沉浸光感收益最大的表面,也是文档最含糊的地方。我们最终落在 openCustomDialog + systemMaterial 上,但中间试错掉的两条路值得展开。

第一条死路:CustomDialogController 的 options 里虽然有 systemMaterial(API 26 新增),但 options 在构造时固定——档位换不了;更糟的是 builder 的编译期约束:

// hilog(真机)
E C0390F/.../AceDialog: CustomDialogController::ConstructorCallback failed!
E C0390F/.../AceDialog: JsOpenDialog failed, jsBuilderFunction is nullptr!

options.builder 必须是"裸的组件调用",包一层箭头函数直接变 nullptr。这个约束让"点按钮 → 按当前档位动态建弹窗"在控制器方案里走不通。

第二条路是内容节点挂材质(customStyle: true + 内容根节点 .systemMaterial(...)),真机同样回了一句 out of scope——内容节点不是白名单表面。

最终方案是"锚组件 + 动态 options":弹窗的打开/关闭都从组件内部走,builder 是组件内部 @Builder 方法的箭头调用(官方文档钦定的形态),每次调用都新建 systemMaterial:

// harmony/cmp_immersive_material/src/main/ets/components/CmpImmersiveDialog.ets - show()(节选)
show(spec: CmpDialogSpec, onPrimary?: () => void, onDismiss?: () => void): void {
  const session: CmpDialogSession = new CmpDialogSession(spec);
  session.onPrimary = onPrimary;
  session.onDismiss = onDismiss;
  // Track A:材质每次现做,档位随调随换;Track B:material 传 undefined
  const material = spec.useSystemMaterial ? CmpMaterialFactory.of(spec.style, true, spec.light, true) : undefined;
  const options: promptAction.CustomDialogOptions = {
    builder: (): void => {
      this.dialogBuilder(session)      // 组件内部 @Builder 方法,不能是裸函数
    },
    alignment: DialogAlignment.Center,
    autoCancel: true,
    maskColor: 'rgba(12, 16, 24, 0.18)',
    systemMaterial: material
  };
  promptAction.openCustomDialog(options).then((id: number) => {
    session.dialogId = id;
  });
}

这里每一行都不是装饰:

  • CmpMaterialFactory.of() 内部先查探针:supported=false 或应用级开关为 DISABLE 时直接返回 undefined——降级逻辑前置到材质工厂;
  • useSystemMaterial 是同一个入口的双轨开关:true 走系统材质壳,false 时内容包进 CmpImmersiveSurface(Track B),标题、正文、按钮的代码一字不改;
  • session 把 spec、回执、dialogId 绑在一起传给 @Builder,关闭按钮直接 session.close() → closeCustomDialog(dialogId),不需要页面记任何状态。

真机全链路日志:

// hilog(真机)
I CMPMaterial: material created REGULAR interactive=true light=#B3FFFFFF
I CMPMaterial: dialog open track=system style=REGULAR material=immersive
I CMPMaterial: dialog opened id=169

track=system / material=immersive 是排查时的关键行:弹窗壳是系统画的还是自绘的、材质对象有没有创建成功。

5.4 Track B:自绘的壳怎么"像"系统

CmpImmersiveSurface 是 Track B 的全部:把 tokens 画成一层皮。

// harmony/cmp_immersive_material/src/main/ets/components/CmpImmersiveSurface.ets - build()(节选)
build() {
  Stack({ alignContent: Alignment.TopStart }) {
    Column() {
      this.content()                       // 内容层,壳不掺和内容
    }
    .padding(this.contentPadding)
    .width('100%')
  }
  .width(this.surfaceWidth)
  .linearGradient({                        // 一次画完「顶部 sheen + 平铺着色」
    angle: 180 - this.tokens.specularAngle,
    colors: [
      [this.sheen(), 0.0],                 // 左上角斜切的高光带
      [this.rgba('#FFFFFF', 0), 0.38],
      [this.tint(), 0.46],                 // 材质着色层
      [this.tint(), 1.0]
    ]
  })
  .borderRadius(this.radius)
  .clip(true)
  .backdropBlur(this.tokens.blurRadius)    // 第 1 层:背景模糊
  .border({ width: this.tokens.edgeWidth, color: this.edge() })   // 第 3 层:边缘高光
  .shadow({                                // 第 4 层:投影
    radius: this.tokens.shadowBlur,
    color: this.rgba('#000000', this.tokens.shadowAlpha),
    offsetX: 0,
    offsetY: this.tokens.shadowOffsetY
  })
  .scale({ /* 按压形变 pressScale */ })
  .animation({ duration: 180, curve: Curve.FastOutSlowIn })
}

三个细节值得单独说:

  1. sheen 和 tint 合并成一个渐变。最初版是两个独立子节点:一个纯色层、一个 sheen 层。结果 height('100%') 的子节点在内容自撑高的 Stack 里反向把父容器撑爆,对照台上五张切片变成五根柱子。改成背景渐变的四个色标,一层画完两层的事,还天然适配任意内容高度。
  2. 模糊在低档位必须显式归零。backdropBlur(0) 与不调用不等价——前者明确表达"这层玻璃没被打磨",也让日志和调试面板能把档位退化如实显示出来。
  3. sheen 的角度跟 tokens 走。specularAngle 单独成参数,是为了让 Kotlin 侧的同名实现能逐字节对齐——对齐的对齐,先对齐参数,再对齐像素。

Kotlin 侧的 CmpImmersiveBackdrop 是同一套结构在 Compose 里的投影:

// cmp/src/commonMain/kotlin/cmp/immersive/material/CmpImmersiveBackdrop.kt(节选)
@Composable
fun CmpImmersiveBackdrop(
    tokens: CmpMaterialTokens,
    modifier: Modifier = Modifier,
    cornerRadius: Int = 24,
    content: @Composable () -> Unit
) {
    Box(
        modifier = modifier
            .shadow(elevation = tokens.shadowBlur.dp, shape = shape, ...)   // 第 4 层
            .clip(shape)
            .background(brush = Brush.linearGradient(                        // 第 2 层:sheen + tint
                colorStops = arrayOf(0.00f to sheen, 0.38f to transparent,
                                     0.46f to tint, 1.00f to tint), ...))
            .border(width = tokens.edgeWidth.dp, color = edge, shape = shape) // 第 3 层
    ) { content() }
}

Compose 画布里没有 backdropBlur 的等价物(那是 ArkUI 节点属性),所以这层"背景采样"在自绘轨道里由宿主把被透出的内容作为 backgroundLayer 先画在材质层下面——参数可以搬,管线搬不动,这是跨端材质体系最硬的一条边界,也是库文档里写明的限制。

5.5 CMP 侧:环境怎么过江

Kotlin 侧不 import 任何鸿蒙 API,它只认一份契约:

// cmp/src/commonMain/kotlin/cmp/immersive/material/CmpMaterial.kt(节选)
interface CmpMaterialHost {
    fun probeEnvironment(): CmpMaterialEnvironment
    fun tokensOf(style: CmpMaterialStyle, dark: Boolean): CmpMaterialTokens
}

object CmpMaterialHostRegistry {
    fun install(host: CmpMaterialHost) { ... }
    fun current(): CmpMaterialHost? = host
}

expect object CmpMaterialPlatform {
    fun probeEnvironment(): CmpMaterialEnvironment
}

ohosMain 的 actual 只做一件事:把宿主注册表里的值递出来,宿主没注册就给出带 degraded=true 的兜底。而"宿主注入"这最后一公里,我用 NAPI 桥打通了——ArkTS 探针探测完,把结果压成三个纯字符串传进 Kotlin:

// cmp/src/ohosMain/.../CmpMaterialHostNapi.kt(节选)
// 库模块内的绑定实现:读 supported / state / level 三个字符串,
// 组装环境并注册宿主,tokens 统一走 common 侧的 CmpMaterialDefaults 标定表
fun cmpMaterialProbeBindingImpl(env: napi_env, info: napi_callback_info): napi_value {
    val args: List<String?> = memScoped { /* napi_get_cb_info 取参 */ }
    val level = when (args.getOrNull(2)?.uppercase()) {
        "EXQUISITE" -> CmpMaterialLevel.EXQUISITE
        "GENTLE"    -> CmpMaterialLevel.GENTLE
        else        -> CmpMaterialLevel.SMOOTH
    }
    CmpMaterialHostRegistry.install(object : CmpMaterialHost {
        override fun probeEnvironment() = CmpMaterialEnvironment(
            supported = args.getOrNull(0) == "true",
            state = args.getOrNull(1) ?: "DEFAULT",
            type = "IMMERSIVE", level = level,
            degraded = !supported, reason = ...)
        override fun tokensOf(style: CmpMaterialStyle, dark: Boolean) =
            CmpMaterialDefaults.tokensOf(style, level, dark)
    })
    return undefinedValue(env)
}

这里有一个很容易被忽略的窗口期:Compose 的首帧可能早于 ArkTS 侧完成注入。所以注入顺序被钉死在壳工程的页面里——先探针、再过桥、最后创建控制器:

// example/harmony/entry/src/main/ets/pages/CmpComposePage.ets(节选)
aboutToAppear(): void {
  // 1. ArkTS 库探针:一次拿到 supported / state / level
  const env: CmpMaterialEnvironment = CmpMaterialProbe.probe();
  // 2. NAPI 桥(libentry.so):注册进 Kotlin 的 CmpMaterialHostRegistry
  KmpMaterialProbe(env.supported ? 'true' : 'false', env.state, levelName(env.level));
  // 3. 最后才创建 Compose 控制器——首帧就能读到正确档位的 token 表
  this.controller = MainArkUIViewController();
}

rememberMaterialTokens() 的语义仍然是"能拿到宿主就用宿主,拿不到就用 common 静态表",静态表数值与 ArkTS 侧严格同源——宁可先画一张默认档的材质,也不许首帧裸奔。

通道只传纯数据(字符串),不传 uiMaterial.Material 对象:材质对象在鸿蒙侧创建、在鸿蒙侧消费(Track A),CMP 画布只消费 token(Track B)。这条边界让库本体不依赖任何互操作版本——cmp/ 在任意 CMP 版本上都能编译,这轮工具链从 1.1.0 升到 1.2.0,库的 commonMain 一行没改。

6. 我踩过的坑

坑一:普通组件挂材质,五条 inactive 全军覆没。

W C03900/.../Ace: Material inactive: out of scope. Use component in navigation title bar or Tabbar.

五档对照台第一版把材质直接挂在普通 Stack 切片上,真机五条 warn,切片全部素颜。排查:对照 .d.ts 里的生效范围说明逐个核对组件类型,确认材质是"白名单表面"制。教训:材质挂载前先问"这个表面在不在白名单里",弹窗/菜单/Sheet/Toast/Select/Slider/Toggle 才是全页面生效的。

坑二:控制器 builder 包一层函数,jsBuilderFunction=nullptr。

E C0390F/.../AceDialog: CustomDialogController::ConstructorCallback failed!
E C0390F/.../AceDialog: JsOpenDialog failed, jsBuilderFunction is nullptr!

我把 builder 写成 cmpDialogOptions((): void => { CmpImmersiveDialog({...}) }, ...) 想做参数化,真机上弹窗毫无反应,hilog 里两行 error。排查:文档里 builder 的说明是"必须形如 () => { this.XXX() } 的箭头函数,XXX 为组件内部 builder"。教训:CustomDialogController 的 builder 是编译期改写的目标,别想把它抽成"可配置的函数"——要动态行为,换 openCustomDialog。

坑三:控制器 options 构造时固定,档位换不动。

即便 builder 写对了,systemMaterial 也是构造时绑定。测试里切 ULTRA_THICK 再开弹窗,壳纹丝不动。排查:hilog 显示 material created 的 style 始终是构造时那档。教训:需要"随档位实时换材质"的弹窗,控制器方案从架构上就不成立,必须每次调用现建 options——这正是锚组件方案存在的原因。

坑四:子节点 height(‘100%’) 在内容自撑高的容器里反向撑爆父容器。

对照台第一版的着色层和 sheen 层是两个 height('100%') 的 Column。真机上五张 60vp 的切片变成五根贯穿屏幕的黄柱。排查:Stack 高度由内容撑起,子节点 height('100%') 的解析基准成了"父容器的可用高度",形成循环放大。教训:自适应高度的壳,装饰层永远走组件自身属性(背景渐变/overlay),不要用全尺寸子节点叠层。

坑五:DevEco 的 hvigor 编译 worker 偶发 Connection refused,整场构建随机挂。

> hvigor ERROR: Error: connect failed: Connection refused
Execution failed for task 'default@CompileArkTS'.

时好时坏,同样的代码五次构建三次失败。排查:发现本机 shell 给所有 node 进程注入了 NODE_OPTIONS=--require=.../node-language-shim.cjs,hvigor 的 worker 走这个 shim 同步文件令牌时被拒。unset NODE_OPTIONS 后构建恢复稳定。

坑六:compatibleSdkVersion 的写法不对,API 版本参数直接被拒。

hvigor ERROR: api version parameter is illegal!
Expected format: <major>[.<minor>][.<patch>], e.g., "17", "17.2", "17.2.3"

我写了 "26.0.0(26)"。排查:这个版本号格式只在 compileSdkVersion 语境合法,compatibleSdkVersion 用 "6.0.0(20)" 一类的写法;且 compileSdkVersion 不需要显式配置,DevEco 内置 SDK 会自动生效。教训:API 26 特性配 compatibleSdkVersion 20 完全能编译(compile 走内置 26),兼容性校验留给运行时。

坑七:签名材料绑死了 bundleName 和版本号。

error: failed to install bundle. code:9568263 error: install version downgrade.     (真机)
error: failed to install bundle. code:9568332 error: install sign info inconsistent. (模拟器)

复用上一篇文章的调试证书,真机嫌版本号低,模拟器嫌签名不一致。排查:真机卸载同 bundle 旧应用、把 versionCode 抬高一档;模拟器直接 hdc uninstall 后重装。

坑八:材质的 materialColor 一旦全不透明,整层材质直接闷死。

// uiMaterial.d.ts 原话(去注释)
The pure color must have a certain transparency value and cannot be completely opaque.
Otherwise, the material filter effect will be completely blocked.

第一版想给弹窗一点品牌色,materialColor 直接给了不透明白。模拟器上玻璃感消失,只剩一块白板。排查:文档明确要求着色必须带透明度。

坑九:@CName 写在库模块里,链接时被 tree-shaking 裁掉。

把 cmpMaterialProbeBinding 的 @CName 导出包装直接写在 cmp/ 库的 ohosMain 里,libkn.so 链接出来用 nm -gU 一看,符号根本不存在,ArkTS 侧调用直接 undefined。排查:K/N sharedLib 只把 app 模块(持有 export 声明的那一层)的 @CName 符号当链接根,库 KLIB 里的 @CName 是死代码,链接器顺手就裁了。教训:导出包装必须写在 composeApp 这个 app 模块,库模块里只留可公开调用的普通函数——K/N 的"根"在 app 层,不在库层。

坑十:字节码 HAR 要求 useNormalizedOHMUrl=true,不开直接构建失败。

hvigor ERROR: 00306046 Specification Limit Violation
Bytecode HAR [@cpf-kmp-cmp/compose] not supported when useNormalizedOHMUrl is not true.

壳工程接上 @cpf-kmp-cmp/compose(Compose 的 ArkUI 宿主组件 HAR)后,hvigor 在 GenerateLoaderJson 阶段拒绝构建。排查:字节码形态的 HAR 与旧版 OHM URL 规则不兼容,工程级 build-profile.json5 里 "useNormalizedOHMUrl" 必须显式设为 true。教训:接字节码 HAR(带 native 产物的 HAR)前,先检查工程的 OHM URL 规范化开关——这是产品级配置,不是模块级。


7. 现在怎么用:从 三方库 到依赖

example 宿主的完整链路已经真机跑通(TLR-AL00):ArkTS 实验室 + CMP Compose 页都是真机验证过的产物,构建是纯命令行,两步——先链 Kotlin,再打鸿蒙:

# 第一步:KMP 构建链出 libkn.so,并同步到壳工程
export JAVA_HOME=<JDK17 路径>
unset NODE_OPTIONS          # 见坑五,环境注入会打挂 hvigor worker
./gradlew :example:composeApp:publishDebugBinariesToHarmonyApp

# 第二步:ArkTS 壳工程打 hap(CMake 会把 libkn.so 一起打进 entry)
cd example/harmony
unset NODE_OPTIONS
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode module -p product=default assembleHap --no-daemon
HDC=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc
$HDC -t <target> install -r entry/build/default/outputs/default/entry-default-signed.hap
$HDC -t <target> shell aa start -a EntryAbility -b com.example.immersiveoverlays

接入三方库(ArkTS 侧)只要三样东西:ohpm 依赖 "@cmp/ohos-immersive-material": "file:../harmony/cmp_immersive_material"、module.json5 里那条 metadata、页面里一个零尺寸锚组件。菜单走 cmpMenuOptions() + bindMenu,自绘面板直接用 CmpImmersiveSurface。CMP 侧则是纯 Compose 依赖 cmp/(KMP 模块),画布内用 rememberMaterialTokens() + CmpImmersiveBackdrop / CmpImmersiveDialog / CmpImmersiveMenu,宿主负责把探针结果经 NAPI 桥注入。


总结:

本文围绕鸿蒙 API 26 ImmersiveMaterial 沉浸光感,落地一套面向 CMP(Compose Multiplatform)的跨端三方库 cmp-ohos-immersive-material,核心解决 Compose 自绘画布无法直接挂载 ArkUI 系统材质的管线限制。系统材质不是通用画笔,属于白名单节点属性,仅弹窗、菜单、Sheet 等浮层以及导航栏、TabBar 可正常生效,普通组件直接挂载会触发 out of scope 警告;同时内置三档算力分级,EXQUISITE、GENTLE 档位启用模糊光感滤镜,SMOOTH 低档直接退化为底色、描边与阴影组合,同一套代码在模拟器和真机上会呈现完全不同视觉效果。

方案设计采用双轨并行架构,Track A 复用原生系统材质,将弹窗、菜单的外层壳交给 ArkUI 承载,通过 openCustomDialog + systemMaterial 动态创建材质实例,跨端 Compose 内容嵌入其中,拿到原生真实的毛玻璃、光感与按压形变;Track B 为画布自绘对齐方案,把系统材质特征拆解为模糊、着色、边缘高光、光泽、阴影五层 token 参数,维护一套五档风格 × 三档算力的二维标定表,ArkTS 与 Kotlin 两侧同源实现,低档设备同步关闭模糊、提升着色透明度,保证跨设备视觉一致性。

工程上拆分为 ArkTS HAR 层、KMP CMP 跨端库、示例宿主三部分,依靠探针组件一次性采集设备支持状态、应用材质开关、全局算力档位,作为全链路降级的总依据;通过 NAPI 桥仅传递纯字符串环境数据,不传递 ArkUI 材质对象,规避跨语言对象无法复用的问题,在 Compose 首帧前完成环境注入,配合 CmpMaterialHostRegistry 建立宿主契约,common 层不耦合鸿蒙平台 API,保证跨平台兼容性。

开发过程中针对鸿蒙原生组件的编译约束、布局渲染特性、构建链路问题逐一验证踩坑:CustomDialogController 的 builder 存在编译期特殊限制,构造时绑定的材质无法动态切换档位;自适应高度容器内全屏子节点会引发布局撑爆;Kotlin/Native 的 @CName 导出符号容易被链接器树摇移除;字节码 HAR 依赖需要开启规范化 OHM URL;hvigor 受 Node 环境变量注入影响会随机构建失败。这些坑都沉淀为库内部的防护逻辑与接入规范。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐