CMP 鸿蒙沉浸光感实战:弹窗菜单复用系统材质,自绘画布按算力档位对齐,打通 CMP 与 ArkUI 双轨渲染链路
沉浸光感不是一层毛玻璃贴图,是 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) |
| 系统 API | HarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0) |
| hvigor | 6.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
三个细节立刻推翻了我的朴素理解:
- 它不是画笔,是节点属性。
systemMaterial(material)挂在组件上,材质由系统在该节点的表面上渲染。画布没有"表面",自绘像素没有"节点",所以 Compose 画布里的东西天生挂不上——这不是封装问题,是管线问题。 - 它有生效范围。弹窗(AlertDialog、CustomDialog、ActionSheet)、菜单(Menu、SelectionMenu)、Sheet、Toast、Select 下拉、Slider、Toggle 这些"浮在内容上的表面"可以全页面生效;其他普通组件只认 Navigation 标题栏和底部悬浮 TabBar,别处设了也白搭——上面那五条 warn 就是证据。
- 它有算力分档。
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 档):

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

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

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


两张对比里我最想让你看的是壳的"厚薄感":自绘菜单的 sheen 从左上角斜切下来,系统菜单的壳则是系统按 THICK 档渲染的一整块材质。
2.2 真机:材质会"素颜"
同一个 example 装上真机(TLR-AL00,SMOOTH 档):

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

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


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

主动交代边界:模拟器上的玻璃感是真材质;真机上的素颜也是真材质——同一套 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 画布:

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

注意两个数字,它们证明了两条链路都通了:
- 状态行
supported=true state=ENABLE level=SMOOTH degraded=false——这不是 Kotlin 自己猜的,是 ArkTS 侧CmpMaterialProbe.probe()探测后经 NAPI 桥传进 Kotlin、注册进CmpMaterialHostRegistry的结果。跨端材质环境注入链路是活的。 - 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 画布里的自绘弹窗浮层:

这个弹窗不是系统弹窗——整层(蒙层、材质卡、按钮)都画在 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 | 应用 → 材质 | 光感反馈颜色 / 按压形变 |
两个细节决定了后面所有的设计:
- 生效范围是白名单制的。弹窗类(AlertDialog、CustomDialog、ActionSheet)、菜单类(Menu、SelectionMenu)、Sheet、Toast、Select、Slider、Toggle 全页面生效;Navigation 标题栏和底部悬浮 TabBar 走专门接口;其余普通组件只在部分场景生效。我们实测的 out of scope 就是这条规则的运行时证据。
- 算力档位决定材质形态。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 })
}
三个细节值得单独说:
- sheen 和 tint 合并成一个渐变。最初版是两个独立子节点:一个纯色层、一个 sheen 层。结果
height('100%')的子节点在内容自撑高的 Stack 里反向把父容器撑爆,对照台上五张切片变成五根柱子。改成背景渐变的四个色标,一层画完两层的事,还天然适配任意内容高度。 - 模糊在低档位必须显式归零。
backdropBlur(0)与不调用不等价——前者明确表达"这层玻璃没被打磨",也让日志和调试面板能把档位退化如实显示出来。 - 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 环境变量注入影响会随机构建失败。这些坑都沉淀为库内部的防护逻辑与接入规范。
更多推荐


所有评论(0)