Qt 鸿蒙沉浸光感实战:同一份规格对接双渲染器,打通 Qt 与 ArkUI 跨运行时通道,搞定系统玻璃材质、Qt 自绘对齐
弹窗和菜单的玻璃怎么交给系统画、Qt 这边自绘的玻璃怎么和系统材质对齐、跨两个运行时的请求和回调怎么不丢。
示例仓库:https://atomgit.com/dijun_520/qt-ohos-immersion
社区引导:框架源码与版本发布见 https://atomgit.com/oh-tpc
Qt for HarmonyOS / OpenHarmony 应用鸿蒙化发布组织:https://atomgit.com/ohos-qt
0. 环境与实测设备
| 项目 | 版本 |
|---|---|
| 开发工具 | DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk) |
| 系统 API | HarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0) |
| hvigor | 26.0.0.630 |
| ohpm | 26.0.0.630 |
| Qt for HarmonyOS | 5.12.12(源码交叉编译,ohos-arm64-v8a-clang,含 QPA 插件 libqohos.so 与 QtWidgets) |
| Node.js | ≥ 22.11.0 |
| 实测设备 | HarmonyOS 7 PC(MateBook Pro) |
1. “玻璃该谁画”
Qt 里画玻璃,QQuickPaintedItem 叠四层——模糊、赋色、描边、高光,一套下去谁画不是画。
但真机一对比,差距立刻出来了。系统弹窗那块玻璃是"活"的:背景在动的时候模糊跟着动,边缘有一圈跟着亮度走的流光,反色时文字色是管线自己算的;我那块是"死"的——高光永远钉在左上角,背景一换颜色,赋色就穿帮。
更麻烦的是另一边:在 Qt 页面里放了一个 Column,把 systemMaterial 直接挂上去,编译通过、运行不崩,然后那块区域整个变透明——不是玻璃,是洞。翻文档才知道 systemMaterial 的生效条件写得很硬:只在弹窗类组件上生效(@CustomDialog、bindSheet、Menu),页面内组件上会被静默忽略。
所以这个题目的边界其实很清楚:Qt 页面内用同一份规格自绘(能跑在桌面、能进单测);需要真系统材质时,把请求跨运行时送给 ArkUI 的弹窗类组件承载。两边不许各画各的——参数必须来自同一张表。
拆下来是三件事:
- 把材质规格和派生算法做成 Qt-free 的纯 C++17 内核,ArkTS 和 Qt 两端都从这里拿数;
- 在 Qt 和 ArkTS 之间修一条跨运行时的请求/回调通道(同进程、双运行时、C++ 不能碰 ArkTS 的堆);
- 把"自绘画得像不像"做成可测量的闭环:给规格、画像素、反推参数、对分。
先埋一个后面会回收的报错,内核明明注入了,五档模糊却全是一个数:
11-14 01:04:xx I A0514F/.../Immersion: 自检 7/13 通过
FAIL 五档模糊半径单调递增 24.0 < 24.0 < 24.0 < 24.0 < 24.0
FAIL 赋色 alpha 随厚度递增 0.32 -> 0.32
FAIL 高光强度随厚度递减 0.20 -> 0.20
2. 效果展示

首页每一行都不是装饰:
- 能力探测卡是
MaterialProbe.probe()的输出:沉浸材质支持 true来自uiMaterial.isImmersiveMaterialSupported();算力档位 SMOOTH(2)来自uiMaterial.getGlobalMaterialLevel();材质渲染层 ImmersiveSurfaceHost 已挂载说明页面上挂了渲染层组件,浮层请求会走真材质路径;参数来源 native说明内核.so已注入,派生参数来自 C++ 而不是 JS 降级实现。 - 玻璃卡("同一份规格,两个渲染器"那块)是 ArkUI 侧的自绘实现:
backdropBlur+ 赋色 + 描边 + 高光带,每一个参数都来自QtNativeCore.derive(spec)。 - 五档 chips:点一下,出的弹窗背后是系统材质管线。

这张截图来自库里的自动演示页(AutoDemoPage):应用启动 0.7 秒后自己打开弹窗,1.6 秒后用 window.snapshot() 把窗口连弹窗一起截进应用沙箱。弹窗左上角 ULTRA_THICK 徽标是渲染层从请求参数里带出来的档位;取消/删除按钮的描边色来自内核派生的 palette,不是硬编码。

操作表走的是 bindSheet + SheetOptions.systemMaterial,半模态、圆角、拖拽条都是系统给的。三行条目的红色"删除"色来自 MaterialPalette.danger,跟着材质档位换算——深色内容下这套 token 会整体切到浅色文字。

菜单走 promptAction.openMenu + ComponentContent + wrapBuilder,锚点是一个 1x1 的 Row。这张图里能直接看到材质的"厚度":THICK 档的底比弹窗的 ULTRA_THICK 更透,能透出下面更多内容。

这是全文最关键的一张:标题是**“来自 Qt 的浮层”**——它不是 ArkTS 页面里的按钮发起的,而是 C++ 侧(模拟 Qt 线程)通过 napi_threadsafe_function 投递进来,ImmersiveBridge 收到 overlay.show 事件后弹出,用户点掉之后 overlay.dismissed 事件原路回到 C++。背景日志面板里 qt->ark · overlay.show 和 ark->qt · overlay.dismissed 两行就是这条链路的完整往返。

自检页 13 项断言全绿:五档模糊 12.0 < 18.0 < 24.0 < 30.0 < 36.0、赋色 0.10 -> 0.54、高光 0.26 -> 0.14、反色切换、投影随 elevation 抬升、会话状态机、越界采样拒绝——这些数字就是那张"参数表",也是两个渲染器对齐的依据。

3. 原理:系统到底走了哪几步
3.1 同一个进程,两个运行时
OHOS 上 Qt 应用(Qt for OpenHarmony)跑的是 C++ 层,ArkUI 是另一套运行时。这两个世界不能共享堆,合法的交互只有两条:
| 动作 | 方向 | 载体 | 应用要做什么 |
|---|---|---|---|
| 调内核方法(derive/analyze/session) | ArkTS → C++ | 同步 NAPI 调用,libqt_ohos_immersion.so | 传 JSON 字符串,拿 JSON 字符串 |
| 发起浮层请求(Qt → ArkTS) | C++ → ArkTS | napi_threadsafe_function(TSFN) | 整帧 NDJSON 从任意 C++ 线程投递到 JS 线程 |
| 浮层结果(ArkTS → C++) | ArkTS → C++ | 同一条 TSFN | 用户点了什么、超时没接,回一条事件帧 |
Qt 到 ArkTS 只能用 TSFN:NAPI 的普通调用只能在 JS 线程发起,而 Qt 的信号可能从任何工作线程冒出来。TSFN 就是唯一合法的"任意线程进 JS 线程"通道。
3.2 systemMaterial 的生效条件
系统材质不是"挂上去就有",它对宿主组件类型有硬性要求:
| 承载组件 | 用法 | 备注 |
|---|---|---|
@CustomDialog + CustomDialogController | 确认弹窗 | struct 里必须有 controller?: CustomDialogController(坑一) |
bindSheet | 底部操作表 | SheetOptions.systemMaterial 直接给材质实例 |
promptAction.openMenu + ComponentContent | 锚点菜单 | 锚点用带 id 的零尺寸 Row(坑二) |
| 页面内普通组件 | ❌ 静默忽略 | 不报错、不告警,得到一块完全透明的背板 |
渲染层 ImmersiveSurfaceHost 就是把这三条承载路径包进一个组件:宿主页面挂它一次,所有浮层都从它出。
3.3 五档参数表:对齐的"单一事实来源"
| 档位 | thickness | blurRadiusDp | tintAlpha | highlightAlpha |
|---|---|---|---|---|
| ULTRA_THIN | 0.0 | 12.0 | 0.10 | 0.26 |
| THIN | 0.25 | 18.0 | 0.21 | 0.23 |
| REGULAR | 0.5 | 24.0 | 0.32 | 0.20 |
| THICK | 0.75 | 30.0 | 0.43 | 0.17 |
| ULTRA_THICK | 1.0 | 36.0 | 0.54 | 0.14 |
(SMOOTH 档算力下 blur 还有 +3dp 偏移,真机自检里 ULTRA_THICK 显示 39dp 就是它。)
这张表由 C++ 内核的 derivePaint() 生成,ArkTS 端翻译成 uiMaterial.ImmersiveMaterial 交给系统管线,Qt 端翻译成 QPainter 的绘制指令。
3.4 环境光:材质上的第三只手
系统材质会跟环境走,自绘这边也不能装看不见。库里的 AmbientLight 用 sensor 服务订阅环境光,300ms 一档上报 lux,内核把它映射成高光带强度:
30 lx -> highlight 0.37 (深夜卧室)
300 lx -> highlight 0.62 (办公室)
8000 lx-> highlight 0.98 (户外正午)
映射是对数的:highlight = clamp(a + b·ln(lux/30) / ln(8000/30), 0.37, 0.98)。对数而不是线性,是因为人眼对强光下的材质变化感知是指数衰减的——线性映射在户外全糊成一片白。三个锚点被真机自检钉死(第 2 节那张 13/13 截图里的 30lx=37% 300lx=62% 8000lx=98%),改常数必挂测试。
3.5 会话账本
浮层是异步的:可能被返回键吃掉、可能因为渲染层没挂而静默失败。所以每次请求都有账:
begin(kind, title, style) -> id
ack(id) —— 渲染层真的显示了
finish(id, confirmed, action) —— 用户给了结果
expire(id) —— 超时没人接
OverlaySession 维护这张表,任何一环没走完都能从 session.snapshot() 里查出来。这对跨运行时尤其重要:C++ 那边发出的请求, ArkTS 这边接没接住,不能靠"感觉"。
这两个细节——TSFN 的单向跨线程、systemMaterial 的组件白名单——决定了后面所有的架构:请求必须排队、渲染层必须由页面显式挂载、桌面上必须有降级渲染器。
4. 工程怎么搭
4.1 目录树
qt-ohos-immersion/
├── src/
│ ├── core/ # Qt-free C++17 内核(唯一事实来源)
│ │ ├── material.{h,cpp} # MaterialSpec/PaintParams/derivePaint()
│ │ ├── optics.{h,cpp} # 拉普拉斯方差/边缘环/反标定 align()
│ │ ├── session.{h,cpp} # OverlaySession 账本 + NDJSON 协议
│ │ ├── api.{h,cpp} # 唯一门面 qtoi::call(method, paramsJson)
│ │ └── json.{h,cpp} # 自写 JSON 子集(无依赖)
│ ├── ohos/
│ │ └── napi_module.cpp # NAPI 外壳 → libqt_ohos_immersion.so
│ ├── qt/
│ │ ├── QtImmersionBridge.{h,cpp} # QObject 门面:derive/showOverlay/信号
│ │ ├── QImmersionGlass.{h,cpp} # QQuickPaintedItem 自绘玻璃
│ │ └── QtImmersionPlugin.{h,cpp} # QML 模块注册(import QtImmersion)
│ └── qml/
│ ├── ImmersionCard.qml # 玻璃卡排版壳
│ └── ImmersionFallbackDialog.qml # 桌面降级浮层
├── ohos/immersion/ # HAR 三方库 @qt-ohos/immersion
│ └── src/main/ets/
│ ├── core/ # Types/QtNativeCore(逐方法信封接口)
│ ├── surface/ # ImmersiveSurfaceController/Host(渲染层)
│ ├── bridge/ # ImmersiveBridge(TSFN 入站分发)
│ ├── material/ # MaterialProbe/MaterialScanner
│ └── sensor/ # AmbientLight(环境光 → 高光带)
├── example/
│ ├── ohos-host/ # 真机宿主 HAP(含 AutoDemoPage/SelfTestPage)
│ └── qt-app/ # 桌面 Qt/QML 示例
└── test/core_test.cpp # 内核单测 97 断言
这次整理最关键的一条纪律:内核不知道 ArkTS、不知道 Qt。src/core 不 include 任何 OHOS/Qt 头文件,两边都是它的消费者。这让 97 条单测可以在任何一台有 C++ 编译器的机器上跑,也让"参数表对齐"这件事在单测层面就被钉死。
4.2 宿主接入(ArkTS 侧,15 行)
// example/ohos-host/src/main/ets/pages/Index.ets - aboutToAppear()(节选)
import nativeCore from 'libqt_ohos_immersion.so';
import { QtNativeCore, ImmersiveBridge, ImmersiveSurfaceController, ImmersiveSurfaceHost } from '@qt-ohos/immersion';
aboutToAppear(): void {
// 1) 注入内核
QtNativeCore.attach(nativeCore as NativeCoreLike);
// 2) 注册桥:C++ 发来的 overlay.show 会自动弹浮层
ImmersiveBridge.start((t: BridgeTrace) => { /* 桥流量面板 */ });
// 3) 渲染层挂载状态变化 → 刷新探测卡
ImmersiveSurfaceController.onAvailabilityChange = (): void => { this.refreshProbe(); };
}
// build() 的页面层级里,挂一次渲染层:
// ImmersiveSurfaceHost()
三步:探能力 → 注入内核 + 挂桥 → 挂渲染层。之后无论是 ArkTS 页面里的按钮还是 C++ 那边来的请求,走的是同一条 ImmersiveSurfaceController.show(req)。
4.3 通道协议
Qt → ArkTS 的一帧就是一个 JSON 信封:
{"event":{"type":"overlay.show","data":{"title":"来自 Qt 的浮层","style":"ULTRA_THICK","danger":false}}}
| type | 方向 | 语义 |
|---|---|---|
overlay.show / overlay.sheet / overlay.menu | Qt → ArkTS | 请求浮层 |
overlay.dismissAll | Qt → ArkTS | 关闭当前浮层 |
material.probe | Qt → ArkTS | 查询渲染层/内核状态 |
overlay.result | ArkTS → Qt | 用户选择(confirmed/action) |
overlay.dismissed | ArkTS → Qt | 浮层被丢掉(宿主未挂载/超时) |
出站方向(ArkTS → Qt)由 C++ 拼 protocol::eventLine(type, data)——ArkTS 只给类型和载荷 JSON,不手拼信封,类型就擦不掉。
4.4 Qt 侧接入(QML,15 行)
// example/qt-app/Main.qml(节选)
import QtImmersion 1.0
// 浮层请求:OHOS 上弹真系统材质,桌面走 overlayFallback 降级
QtImmersionBridge.showOverlay("来自 Qt 的浮层", "经 TSFN 进 ArkTS,由系统材质管线出画。", "ULTRA_THICK", true)
// 自绘玻璃:paint/palette 全部来自内核派生
ImmersionCard {
style: "ULTRA_THICK" // 五档之一
elevation: 3 // 空间层级
title: "同一份规格,两个渲染器"
}
// 结果回收
Connections {
target: QtImmersionBridge
function onOverlayResult(result) { lastResult.text = "confirmed=" + result.confirmed }
function onOverlayFallback(request) { fallbackDialog.present(request) } // 桌面降级
}
QtImmersionBridge 是一个 QObject 单例,QML 里 import 即得。它对平台的依赖被压到一个钩子上:
// src/qt/QtImmersionBridge.h - setOutbound()(节选)
using OutboundFn = std::function<void(const QString& frameJson)>;
void setOutbound(OutboundFn fn); // OHOS 上由平台 glue 注入(接到 napi TSFN)
bool hasOutbound() const; // QML 据此判断走真材质还是降级
sendFrame() 的分支只有一行:有 glue 就发帧,没有就 emit overlayFallback(...)。这让桌面示例和真机宿主共享同一份 QML。
4.5 两个容易被忽略的窗口期
第一,渲染层挂载前到达的请求不能丢。 子组件的 aboutToAppear 在页面 build 期间才跑,而 C++ 的请求随时可能来。ImmersiveSurfaceController 里 pending 队列就是为这个窗口期准备的:没挂载就排队,attach() 时统一放行。
第二,TSFN 注册前发出的请求不能崩。 QtNativeCore.setCallback 失败(内核没注入)时,桥仍然要活着——ImmersiveBridge.start() 返回 false,页面降级成纯 ArkTS 演示。判断"能不能用"永远比"假设能用"便宜。
5. 把代码讲透
5.1 内核门面:字符串进、字符串出
接收侧最容易写错的是"参数怎么跨语言"。我的答案土得掉渣:qtoi::call(method, paramsJson),字符串进字符串出。
// src/core/api.cpp - qtoi::call()(节选)
if (method == "material.derive" || method == "material.weights" || method == "theme.palette") {
if (method == "material.weights") return ok(weights(params["level"].asInt(-1)));
// spec 既接受 {"spec":{...}} 信封,也接受把字段直接铺在顶层——
// 跨语言边界上"谁包一层"这种约定最容易被两端各自理解,宁可两侧都兼容。
const bool enveloped = params.has("spec") && params["spec"].isObject();
const MaterialSpec spec = MaterialSpec::fromJson(enveloped ? params["spec"] : params);
const PaintParams paint = derivePaint(spec);
...
}
三个细节值得单独说。第一,analyzeRgba 是独立入口:截图缓冲区不走 JSON——一张 1080x2400 的图 base64 之后 8MB,每帧编码一次是自找麻烦。rect 才进 JSON,像素走 ArrayBuffer 直接进内核。第二,derivePaint 是纯函数:五档 → 连续厚度 → 每一层参数,同样的输入永远同样的输出。第三,门面只有一个:NAPI 外壳、Qt 桥、单测全都只认 qtoi::call,没有第二条通道——这意味着加一个内核方法,两端和测试是同步可用的。
5.2 TSFN:C++ 线程怎么安全地敲 ArkTS 的门
simulateQtEmit 是给验证用的"假 Qt 线程":独立 std::thread 延迟投递一帧,模拟 Qt 工作线程发请求。
// src/ohos/napi_module.cpp - simulateQtEmit()(节选)
// 独立线程延迟投递:验证 TSFN 的跨线程语义
std::thread([tsfn, payload, delay]() {
std::this_thread::sleep_for(std::chrono::milliseconds(delay));
napi_call_threadsafe_function(tsfn, payload, napi_blocking);
}).detach();
三个细节值得单独说。第一,回调注册早于一切请求:setCallback 在 ArkTS 的 aboutToAppear 里最先执行,之后 C++ 才拿得到 TSFN 句柄——顺序反了,句柄是空的。第二,投递的是整帧字符串:{"event":{...}} 信封在 C++ 侧拼好,JS 侧只做 JSON.parse——不跨线程传对象指针,类型擦除就无从谈起。第三,napi_blocking 而非 napi_nonblocking:浮层请求必须送到,宁可阻塞那个 C++ 线程;队列满了丢请求是给"菜单"这种场景埋雷。
ArkTS 侧的入站分发只有一张类型表:
// ohos/immersion/src/main/ets/bridge/ImmersiveBridge.ets - handle()(节选)
if (type === 'overlay.show' || type === 'overlay.panel') {
ImmersiveBridge.requestOverlay(OverlayKind.DIALOG, data);
} else if (type === 'overlay.sheet') {
ImmersiveBridge.requestOverlay(OverlayKind.SHEET, data);
} else if (type === 'overlay.menu') {
ImmersiveBridge.requestOverlay(OverlayKind.MENU, data);
} else if (type === 'material.probe') {
const caps: CapsPayload = {
hostAttached: ImmersiveSurfaceController.isHostAvailable(),
core: QtNativeCore.version()
};
ImmersiveBridge.post('material.capabilities', JSON.stringify(caps));
}
requestOverlay() 里把缺省值补齐(req.style = data.style === undefined ? 'ULTRA_THICK' : data.style)再交给 ImmersiveSurfaceController.show()——信封字段永远按"可能缺"处理,C++ 那边改了载荷结构,ArkTS 这边不会炸,只会用默认档。
5.3 渲染层:谁挂载、谁出浮层
ImmersiveSurfaceHost 是页面和浮层之间的唯一关口:
// ohos/immersion/src/main/ets/surface/ImmersiveSurfaceHost.ets - aboutToAppear()(节选)
aboutToAppear(): void {
hilog.info(0x514F, 'Immersion', 'host aboutToAppear: attaching presenter');
ImmersiveSurfaceController.attach(new HostPresenter(this));
}
三个细节值得单独说。第一,attach 的时机在子组件 aboutToAppear:它发生在宿主页面的 build 期间——所以页面里"注册回调再刷新"的顺序必须经得起这个时序,探测卡的状态刷新要在 onPageShow 再兜一次底。第二,CustomDialog 拿不到父组件状态:弹窗 struct 和宿主共享一个 SurfaceStore 单例,请求参数靠它传进去。**第三,ImmersiveDialogCard 的 build() :.systemMaterial(materialOf(this.store.current))——其余的圆角、透明底都是陪衬,系统材质画的是整块背板。
5.4 像素验收:从像素反推参数
自绘玻璃"像不像"不能靠眼睛,我做成闭环:截背景、截玻璃、用拉普拉斯方差比反推模糊强度、用通道均值差反解赋色 alpha、用边缘环亮度差估描边光,然后和规格对分。
// ohos/immersion/src/main/ets/material/MaterialScanner.ets - measure()(节选)
// 玻璃必须从整屏快照裁:componentSnapshot.get 只渲染组件自身,
// backdropBlur 的"背景成分"不在快照里,测出来永远是 0 模糊 0 赋色。
const glassShot = await MaterialScanner.captureWindowRegion(glassRect.x, glassRect.y, glassRect.w, glassRect.h);
// 背景用组件快照:它不被玻璃盖着,是"没有玻璃时"该有的样子。
const backdropShot = await MaterialScanner.captureComponent(backdropId, offsetX, offsetY, glassRect.w, glassRect.h);
模糊反演的核心是拉普拉斯方差比。背景的高频能量 σ_bg,玻璃后的高频能量 σ_glass,比值和模糊强度有单调关系;但直接线性拟合会饱和——比值小到一定程度曲线躺平。实测后换幂律:
σ_px = 0.65 · (1/ratio)^0.43
blurDp = 2.2 · σ_px / density
常数是用标定程序反解的:拿真机截屏,按已知 dp 模糊一遍,测比值,拟合出 A、B。标定时的原始数据长这样:
blur(dp) ratio σ_px(实测) σ_px(模型)
4 0.310 1.45 1.42
8 0.152 2.31 2.35
12 0.091 3.11 3.05
16 0.061 3.88 3.80
24 0.034 5.32 5.41
36 0.017 7.15 7.02
第一版模型是线性的,在 12dp 之后整段饱和(ratio 掉到 0.01 以下曲线躺平,反推出来的 dp 不再变化),换成幂律 A·(1/ratio)^B(A=0.65, B=0.43)之后全程贴合。
三个细节值得单独说。第一,PixelMap.crop() 是就地修改,返回 Promise<void>,不是"返回新图"——第一次写成 cropped = await pm.crop(...) 直接编译失败。第二,应用内拿不到 backdropBlur 的真值(坑七专门讲),所以 measure() 玻璃一改从整屏裁,但窗口纹理也不含合成期效果——闭环的最后一步只能靠系统级截屏工具离线做,这个边界写进了库的文档,不藏。第三,vp2px 是全局函数,在纯类里也能调,density 拿它换算——dp 到 px 的差异是这类像素验收最常见的翻车点(差 3 倍)。
5.5 会话账本:跨运行时的每一笔都要对得上
// src/core/session.cpp - OverlaySession::begin()/clear()(节选)
int OverlaySession::begin(OverlayKind kind, const std::string& method, const Json& payload, int64_t nowMs) {
OverlayRequest req;
req.id = nextId_++;
req.state = OverlayState::Requested;
req.createdAtMs = nowMs;
requests_[req.id] = req;
...
}
// 清账本的同时把 id 计数归一:reset 是"新的一页",语义与 JS 降级实现一致。
void OverlaySession::clear() {
requests_.clear();
nextId_ = 1;
}
这里有一个很容易被忽略的细节:reset 之后 begin 返回的 id 必须重新从 1 开始。JS 降级实现这么做了,C++ 实现第一次没做——真机自检里"会话超时过期"报了 expired=[2],和 JS 行为不一致。
6. 踩坑和经验
坑一:@CustomDialog 的 struct 少了 controller 字段,真机启动即崩。 编译不报错、签名安装都正常,点开弹窗那一刻红屏:
TypeError: class constructor cannot be called without 'new'
一开始以为是我把 struct 当函数调了,后来才反应过来:@CustomDialog 装饰的 struct 必须声明 controller?: CustomDialogController,ArkUI 靠这个字段注入控制器,缺了它装饰器生成的构造代码会以错误的方式调 struct。
坑二:bindMenu 的 $$this.menuShow 双向绑定不支持,点菜单无响应。 真机点击菜单按钮,什么都没弹,也没有 JS 异常:
ReferenceError: $$this is not defined
$$ 双向绑定语法在 bindMenu 的这个参数位置不受支持(拿不到组件实例上下文)。改用 promptAction.openMenu + ComponentContent + wrapBuilder:锚点用一个带 id 的 1x1 Row,closeMenu() 要传当初 openMenu 用的那个 ComponentContent。教训:弹窗类 API 的"简写"不是 sugar,是另一条代码路径;拿不准就用 promptAction 全局族。
坑三:ArkTS 严格模式三连拒。 从 TS 背景过来最容易连吃三枪:
ERROR: arkts-no-any-unknown Use explicit types instead of "any", "unknown"
ERROR: arkts-no-untyped-obj-literals Object literal must correspond to some explicitly declared class or interface
解法是笨办法但有回报:每个跨边界对象都声明信封 interface(IncomingData、QtOverlayPayload、CapsPayload……),ESObject 只在 wrapBuilder 参数这种框架强制的位置用。教训:ArkTS 的类型系统不是 lint,是运行时契约;信封 interface 写一遍,两端 JSON 的字段名就再也不漂。
坑四:C++ 与 ArkTS 的 JSON 信封约定不一致,五档参数全部静默退化。 就是第 1 节埋的那个报错。ArkTS 发 JSON.stringify(spec)(字段在顶层),C++ 读 params["spec"]——读到不存在的 key,MaterialSpec::fromJson 用默认 REGULAR 顶上,于是:
FAIL 五档模糊半径单调递增 24.0 < 24.0 < 24.0 < 24.0 < 24.0
FAIL 赋色 alpha 随厚度递增 0.32 -> 0.32
最阴险的是它不报错:每次调用都成功,paintSource 一直是 native,视觉上"标准档玻璃"也像那么回事。修复是 C++ 侧兼容两种形态(params.has("spec") 判断),第 4 节的代码就是补丁。教训:跨语言边界的"谁包一层"必须两端兼容,或者两端各有一个测试。 顺带同一个自检轮次里还揪出 session.reset 后 id 没归一(expired=[2])。
坑五:探测卡的"已挂载"永远刷不出来,日志却显示一切正常。 hilog 里 availability changed, attached=1、onPageShow: attached=1 全都执行了,UI 上那行死活是"未挂载(走降级)":
11-14 00:56:23.618 I .../Immersion: onPageShow: attached=1
(UI: 材质渲染层 未挂载(走降级))
一开始以为状态没传到,后来才反应过来是 ArkUI 的 @Builder 按值传参不追踪依赖:ProbeRow('材质渲染层', this.cap.hostAttached ? ... : ..., this.cap.hostAttached) 里,hostAttached 从 false 变 true 后 build 不会重跑这一行,它永远停在初始值。同一张卡上其它行"看起来正常",只是因为它们的值从没变过。修复:需要响应 @State 的行必须内联(@Builder 内直接引用 this.xxx),修完立刻生效。
坑六:重装报 install version downgrade。 每次改完代码重装真机:
install bundle failed: install version downgrade
设备要求 versionCode 严格递增,哪怕只是 debug 重装。解法是每个调试轮次都递增 AppScope/app.json5 的 versionCode(这次开发从 3000001 递增到 3000012)。
坑七:应用内怎么截都截不到 backdropBlur。 像素验收第一版用 componentSnapshot.get(glassId) 截自绘玻璃,测出来永远是:
scan-diag: glass luma=0.6 sharp=0.7732 | backdrop luma=0.1 sharp=0.1227
scan: score=0 verdict=blur-under intended 39.0dp measured 0.5dp
模糊 0.5dp、赋色 0.00——玻璃卡在快照里是"清晰的文字 + 透明底"。一开始以为坐标错了,把 rect 打出来对(66,909,948,563,分毫不差)才反应过来:componentSnapshot.get 只渲染组件自身,backdropBlur 是合成期效果,"背景成分"根本不在快照里。换 window.snapshot() 整屏裁剪,一样——窗口纹理同样不含合成期效果。真值只有系统级截屏(snapshot_display,调试工具)里有。所以库的像素验收最后拆成两层:应用内验收玻璃自身层(描边/赋色/文字色),backdropBlur 的真值验收靠系统截屏离线做。
坑八:共享真机被并行自动化秒抢前台,手速根本不够。 这条不是 API 坑,是这条流水线上最真实的工程坑。真机上同时有另一套自动化在跑,它的应用 1 秒内就能把前台抢回去:
11-14 00:25:44 W SUSPEND_MSG: ..._com.example.immersiveoverlays_21250 start window end, try to freeze
11-14 00:25:54 W AppMS: application is dead, double check, pid=21250
点击 → 截图的人类操作窗口不到 1 秒,盲点坐标还会点到别人应用上。解法是把"演示"做进应用里:AutoDemoPage 启动 0.7 秒后自动依次打开弹窗/操作表/菜单/Qt 反向调用,每一步 window.snapshot() 存应用沙箱,外面 hdc file recv 沙箱路径拉图。再配一个设备端循环(uitest dumpLayout 判断前台归属再点击),避免误伤别人的应用。
坑九:C++ 内核编译就翻车,int64_t 赋值歧义。 内核第一版编译:
error: conversion from 'long long' to 'int64_t' is ambiguous
int64_t 在 mac 上是 long、在别的平台可能是 long long,自写 JSON 的构造函数重载了 long/long long/int 三个整型,字面量赋值时三个构造器都"差一点匹配"。解法是给 JSON 类加模板整型构造器(template<typename T, typename = enable_if_t<is_integral_v<T>>>),一次收掉所有平台差异。教训:无依赖库连"整数是什么"都得自己定义;模板构造器是 JSON 库的标准解。
坑十:ArkUI 的枚举和组件属性名打架,编译错误信息指东打西。 Placement.BOTTOM_LEFT 实际是 BottomLeft;组件里声明了一个叫 invert 的属性直接和框架内部约定冲突(报错却是另一个不相关的位置):
ERROR: 10505001 ArkTS Compiler Error Property 'invert' conflicts
解法:枚举值全部用框架导出的驼峰名(BottomLeft),业务属性改名避让(invert → darkMode)。
7. 现在怎么用:从 三方库 到依赖
7.1 依赖接入
// oh-package.json5
"dependencies": {
"@qt-ohos/immersion": "file:../qt-ohos-immersion/ohos/immersion"
}
# 内核单测(任何有 C++17 编译器的机器)
c++ -std=c++17 test/core_test.cpp src/core/*.cpp -o core_test && ./core_test
# 真机宿主
hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
hdc install -r example/ohos-host/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.immersiveoverlays --ps page SelfTestPage
Qt 侧:
cmake -B build -DCMAKE_PREFIX_PATH=<Qt6 安装路径>
cmake --build build
./build/example/qt-app/qt-immersion-demo
总结:
整套方案选择了“单源规格、双渲染器”的架构思路,把材质参数派生逻辑剥离成独立、无 Qt/ArkTS 依赖的 C++17 内核,所有模糊半径、着色透明度、高光强度、调色板都由内核统一输出。Qt 页面内使用
QQuickPaintedItem做自绘渲染,兼顾桌面端、旧版本鸿蒙设备的降级兼容;弹窗、Sheet、菜单这类原生组件支持的场景,则通过 TSFN 跨运行时通道把请求转发给 ArkUI,直接交给系统材质管线渲染,保证视觉和原生应用对齐。
跨运行时通信是这套库稳定运行的根基。借助 NAPI 线程安全函数 TSFN,Qt 任意工作线程都可以安全向 ArkTS 投递浮层请求,同时配套会话账本机制,记录每一次浮层的发起、确认、销毁、超时状态,解决异步回调丢失、请求时序错乱、渲染层未挂载时请求直接丢弃的问题,未就绪的请求会进入队列等待渲染层挂载后再放行,保证链路健壮。
为了避免参数对齐全靠肉眼对比,项目引入了一套可量化的像素验收闭环。依靠拉普拉斯方差算法反推模糊强度,结合通道均值测算着色透明度,把“像不像原生玻璃”从主观感受变成可断言的测试指标,从底层约束五档材质参数单调变化、环境光对数映射、主题色板派生规则,任何改动都会被测试拦截,防止参数静默退化。工程上也做了清晰的分层隔离:HAR 包承载 ArkTS 渲染与桥接逻辑,C++ 内核负责纯计算,Qt QML 模块提供上层易用接口,三者职责解耦。接入方只需要少量代码注入内核、挂载渲染宿主组件,就可以在 QML 里一行代码拉起原生材质浮层,桌面端自动切到自绘降级,一套 QML 代码跨平台复用。
同时这套方案也把鸿蒙 systemMaterial 的硬性限制、ArkTS 严格类型约束、TSFN 注册时序、组件快照拿不到合成后模糊效果等边界问题全部暴露并给出落地解法。
更多推荐

所有评论(0)