ReactNative鸿蒙实况窗实战:让订单状态“跟着JS走“
JS 侧一条命令怎么抵达 ArkTS 的实况窗服务、payload 怎样过桥才能一字不差、手写 JSI 胶水到底胶在哪——这篇文章用一个 RN 0.84 + RNOH 0.84 的工程,把发布链路逐跳摊开给你看。
仓库地址:https://atomgit.com/oh-react-native/live-view-rn
版本地址:https://atomgit.com/CPF-rn
三方库框架:https://atomgit.com/oh-react-native
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 26.0.0.851(HarmonyOS SDK 26.0.0 Release / API 26) |
| React Native | 0.84.1(Hermes,release minified bundle) |
| RNOH | 0.84.3(@react-native-oh/react-native-harmony) |
| 实况窗 SDK | @hms.core.liveview.liveViewManager(@kit.LiveViewKit) |
| 实测设备 | Mate 90 Pro 镜像模拟器,OpenHarmony 7.0.0.107(API 26,ohos-x64) |
| 测量通道 | hilog(RNOH_JS 的 console.log + A00000/LiveViewRN)+ 应用内日志页 |
| 插件 | live-view-rn 1.0.0(本仓库,file 依赖) |
1. 这道题的来源
系列做到实况窗这一站,分工早就定了:Flutter 成员做全桥接(它负责把系统级实拍带回来),Cordova 成员做零原生的 payload 层(WebView 沙箱摸不到 kit),而 RN 在中间——负责 JS 侧与 ArkTS 侧之间的桥接。
动手之前,我的理解很朴素:RNOH 都把 TurboModule 体系带到鸿蒙了,写个 TS 接口、ArkTS 实现一下,TurboModuleRegistry.get('LiveView') 一调就通了吧?真上手才发现,这个"通"字对应三个问题:桥的胶水要自己手写(build 期 codegen 在独立工程解析不了)、payload 的序列化规则两端各一套(事件通道把 Map 吃成 {})、每跳的耗时与语义要逐跳证明("应该到了"和"到了"是两回事)。
所以这道题的边界很清楚:在 RN 里,把实况窗的发布链路做成一条可逐跳验证的桥——JS 侧纯 TS 的 payload 构造层产出与 kit 字段一字不差的 spec,ArkTS 侧 TurboModule 逐字段装配后调 liveViewManager,中间每一跳都留 hilog 铁证。拆成三件事:
- payload 构造层(外卖 / 打车 / 比分三场景状态机的纯 TS 实现,vitest 锚定);
- 桥接层(AnyThreadTurboModule + 手写 JSI 胶水 + wantAgent 注入);
- 应用内实验室(三场景 + 日志页,发布结果实时回流)。
2. 效果展示
先看效果,再讲原理。Demo 还是那个"实况窗实验室",RN 版四个 Tab:外卖、打车、比分、系统与日志。
外卖页首屏:徽章已经转绿——“系统实况窗服务在”(来自 probe,586ms 返回 enabled=true);往下是胶囊态预览(计时/文本/进度三种形态都支持)、卡片态预览、步骤指示器、四个操作按钮,最底下是本次 payload 的 JSON 全文:

打车页是这套 UI 里信息密度最高的一屏:胶囊切到计时形态(“呼叫中 · 已等待 00:00”,kit 的 TimerCapsule 语义),卡片扩展区切到强调文本模板(“呼叫中 / 等待司机接单”),辅助区挂"标准型"徽标;接单之后同一张卡会变成大号车牌"京A·8P9X2"加蓝色下划线:

比分页走比分模板(ScoreLayout):主客队、比分、赛事描述、比赛时间;胶囊标题传"数字:数字"时 6.0.0(20) 起系统自动渲染队徽样式。三次"下一步"推到 2:1:
比分的胶囊标题还有一个方向性判断值得单独说:预览器渲染的是 payload 字段的忠实投影,系统侧的加成只会比预览更多,不会更少。队徽化、归档动画、深色模式适配都是系统侧的自由裁量,应用管好字段就够了。这条原则让三端预览器的设计收敛到同一个结论:不模仿系统的加成,只忠实呈现自己的输入。

打车页值得多看一眼的是胶囊形态的三次切换:呼叫中是 TimerCapsule(正计时时钟,kit 每秒自己走针,应用不用刷)、司机接单后切 TextCapsule(“京A·8P9X2 · 距您 1.8km”,6.0.0(20) 起车牌这类"键值对"文案还有专属的车牌样式)、行程中切 ProgressCapsule(45/100)。切换不需要结束重建——三次 update,每次只改 capsule 字段,kit 侧无缝过渡。
完整六步的字段变化逐条核过(设计 payload 层时对照官方模板文档做的表):
| 步骤 | 扩展区模板 | 胶囊形态 | 胶囊文案 | 关键字段变化 |
|---|---|---|---|---|
| 呼叫中 | PickupLayout(“呼叫中 / 等待司机接单”) | TimerCapsule(正计时) | “呼叫中 · 已等待” | isCountdown=false |
| 司机已接单 | PickupLayout(车牌 + 下划线) | TextCapsule | “京A·8P9X2 · 距您 1.8km” | underlineColor=#FF007DFF |
| 即将到达 | PickupLayout(不变) | TextCapsule | “距您 300m · 约 2 分钟” | 只动胶囊文案 |
| 已到达 | PickupLayout(不变) | TextCapsule | “已到达 · 请上车” | — |
| 行程中 | 切 ProgressLayout(45%) | 切 ProgressCapsule | “行程中” | 模板切换(PROGRESS=3) |
| 行程结束 | ProgressLayout(100%) | ProgressCapsule | “行程结束” | keepTime=300 |
这张表对应的正是 vitest 里"模板与胶囊随步骤切换"的断言组——表里的每一行在测试里都有一个对应用例,payload 层与官方模板文档从此有了一张可执行的对照表。
顺带一提,sequence 的要求在这张表里看不出来:六步共享一条递增链,哪一步的 update 都不能回退版本号——这也是 vitest 的第一组用例(strictly growing sequence)存在的原因。外卖与比分的表同构,只是模板与文案不同;三张表加起来就是三件套的"公共语义"在场景维度的全部内容。
发布结果全部实时回流到"系统与日志"页:每条 start/update/stop 的 op、sequence、resultCode 都是一条带颜色的流水(绿 0 红 非0),与 hilog 逐条对得上:

关键的数值行内嵌在 hilog 里:probe 586ms(引擎 Running → 回包落地);publish 的 JS→ArkTS 单跳 2ms;整条打车发布的逐跳时间线:
16:49:47.175 RNOH_JS LVK-JS calling native start ← JS 发起
16:49:47.177 LiveViewRN publish entered start ← JSI 胶水送达 ArkTS
16:49:47.192 LiveViewRN clickAction agent ready ← wantAgent 构建完成
16:49:47.192 LiveViewRN start id=1002 seq=2 event=TAXI ← kit 调用入参
以外卖为例,把"每一步系统侧长什么样"完整走一遍——设计 payload 层时逐字段对照官方模板文档核出来的表:
| 步骤 | 扩展区模板 | 胶囊形态 | 胶囊文案 | 关键字段变化 |
|---|---|---|---|---|
| 已下单 | ProgressLayout(10%,虚线) | ProgressCapsule | “等待商家接单” | progress=10/max=100 |
| 商家接单 | ProgressLayout(25%) | ProgressCapsule | “商家出餐中” | subEvent=FOOD 全程不变 |
| 骑手取餐 | ProgressLayout(60%) | ProgressCapsule | “骑手取餐中” | 辅助区切"取餐码 8829" |
| 配送中 | ProgressLayout(85%) | ProgressCapsule | “距您 1.2km” | lineType 不传(运行时更严) |
| 已送达 | ProgressLayout(100%,实线) | ProgressCapsule | “已送达” | keepTime=600 归档 |
打车与比分同理会走各自的形态切换:打车从 TimerCapsule(呼叫计时)切 TextCapsule(车牌)再切 ProgressCapsule(行程),比分全程 ScoreLayout、只动 hostScore/guestScore/competitionTime 三个字段与胶囊标题。这套"模板与胶囊随步骤推进切换"的节奏,是状态机层最有复用价值的部分——三端的状态机表是逐字对齐的。
3. 原理:一条命令的六跳
写代码之前先把链路列清楚。JS 侧一句 lv.publish('start', snap),到 kit 收到参数,中间要经过六跳:
JS: publish(op, snap)
① payload 构造层 snap.spec # 纯 TS,字段名/枚举值锚定 kit
② 序列化 JSON.stringify # 整份 spec 塞进一个字符串
③ JSI 胶水 methodMap_ # 手写 C++:按方法名转发
④ ArkTS 模块 specFromJson # 逐字段重装配成 kit 接口对象
⑤ 运行时契约 默认值注入 # clickAction/nodeIcons/...
⑥ kit 调用 liveViewManager.startLiveView(spec)
为什么 payload 层要独立成纯 TS? 因为它承载的是"契约":字段名、枚举值(LayoutType.PROGRESS=3、CapsuleType.TIMER=2……)、不变式(sequence 严格递增、shareUrl HTTPS <128)——这些数字穿过桥之后不再有类型系统保护,必须有一层可单测的东西把它们钉死。liveViewPayload.ts 零 react-native 依赖,vitest 直接跑,15 个测试把每个枚举值和场景不变式锁死。
为什么 spec 要走一条 JSON 字符串? 因为 RNOH 的序列化规则两端不对称:JS→ArkTS 的对象参数能过,但事件通道(ArkTS→JS)会把 Map 实例序列化成 {}——嵌套结构在任何方向上都有走样风险。字符串是唯一两端都不会变形的形状。代价是 ArkTS 侧需要一个逐字段装配器(specFromJson),换来的是"契约只在两处显式存在:TS 的类型层和 ArkTS 的装配层"。
为什么胶水要手写? RNOH 的 build 期 codegen(@rnoh/hvigor-plugin)在独立工程里解析不了依赖,codegen-harmony 只扫 node_modules 里声明的 codegenConfig——仓库根自己的 spec 谁也不扫。手写的 LiveViewSpecJSI 就是 codegen 本该生成的那 40 行:methodMap_ 按 JSI 约定登记每个方法名与参数个数,C++ 壳按名字转发进 ArkTS。方法表漏一项的症状是那条命令永远 pending——没有报错也没有日志,所以 spec 里的每个方法都要在表里有一行。
运行时契约就是第五跳存在的理由。 kit 的 d.ts 把 clickAction、nodeIcons、capsule.icon、capsule.backgroundColor、descPic 全标成可选,而 API 26 模拟器上的实况窗服务逐字段校验、缺一就 Error(401)。模块在装配后统一注入默认值:wantAgent 指向宿主 EntryAbility,图标默认 lv_node_a.png(随包资源)——应用传了自己的就用自己的。
4. 工程怎么搭:库、壳、宿主三层
live-view-rn/
├─ src/index.ts # 公共出口
├─ src/types.ts # 线上协议类型(判别联合,字面量枚举)
├─ src/liveViewPayload.ts # 纯 TS 场景构造层(vitest 锚定)
├─ src/NativeLiveView.ts # TurboModule spec("LiveView")
├─ src/decoders.ts # 桥回包的宽松解码
├─ src/useLiveView.ts # React hook(probe + 事件订阅 + publish)
├─ harmony/rn_live_view/ # 源码 HAR
│ ├─ Index.ets / oh-package.json5 / build-profile.json5
│ └─ src/main/ets/
│ ├─ LiveViewModule.ets # TurboModule + specFromJson + 契约注入
│ └─ LiveViewPackage.ets # 注册 "LiveView" 到 AnyThread 工厂表
├─ example/
│ ├─ App.tsx # 实况窗实验室(三场景 + 日志页)
│ ├─ harmony/entry/src/main/cpp/
│ │ ├─ LiveViewPackage.h # 手写 JSI 胶水(methodMap_ 5 项)
│ │ ├─ generated/RNOHGeneratedPackage.h # 空壳包头(见坑七)
│ │ └─ CMakeLists.txt # ffrt x86_64 imported target 补丁
│ ├─ harmony/entry/src/main/resources/rawfile/lv_node_a.png / b
└─ __tests__/ # 15 个 vitest(枚举值 + 场景不变式)
宿主接线四步(也是任何 RN 库接鸿蒙系统能力的通用姿势):
oh-package.json5加依赖:"@rnoh/live-view-rn": "file:../../../harmony/rn_live_view";RNPackagesFactory.ets:return [new LiveViewPackage(ctx)];- cpp 胶水:
LiveViewPackage.h(方法表)+PackageProvider.cpp里make_shared; - x86_64 模拟器:CMakeLists 里补 ffrt imported target(RNOH 0.84.3 的 upstream 缺口,注释里写了来龙去脉)。
使用方 API 全部从一个 hook 进出:
const lv = useLiveView();
// lv.supported / lv.probe {present, enabled, detail} / lv.publishLog
const delivery = new DeliveryScenario();
await lv.publish('start', delivery.snapshot(0)); // 创建(sequence=1)
await lv.publish('update', delivery.snapshot(1)); // 更新(sequence=2)
await lv.publish('stop', delivery.snapshot(4)); // 结束(keepTime 归档)
hook 内部就三段:挂载时 DeviceEventEmitter 订阅 + 一次 probe;publish 把 spec 序列化后按 op 分发到对应的 Native 方法;事件回调里 decodePublishOutcome 宽松解码后喂进日志。UI 侧(App.tsx)再叠一层组件:CapsulePill(胶囊预览,三种形态分派)、CardPreview(卡片三区,按 layoutType 分派 Progress/Pickup/Score 三个子组件)、SwipeShareCard(PanResponder 左滑分享模拟)。预览组件与 payload 层共享同一套字面量枚举,不再维护第二份默认值表。
运行时契约(第五跳的注入清单)目前有六项,全部出自真实 401:
| 字段 | 归属 | kit 报错(节选) | 默认注入 |
|---|---|---|---|
| primary.clickAction | 固定区 | must be WantAgent | 宿主 EntryAbility 的 START_ABILITY |
| layoutData.nodeIcons | 进度条模板 | must be Array<string | image.PixelMap> | lv_node_a/b.png |
| layoutData.descPic | 强调文本模板 | must be string | image.PixelMap | lv_node_a.png |
| capsule.icon | 胶囊 | must be string | image.PixelMap | lv_node_a.png |
| capsule.backgroundColor | 胶囊 | must be string | #FF007DFF |
| RichText.textColor | 富文本 | 转换器 parse napi object type fail | #99000000 |
这张表是三端共用的——Flutter 成员的 verification.md 记了另外四条,descPic 是 RN 成员首发发现的。任何新模板接入前,先照这张表把"运行时必传"核一遍,能省掉真机上最磨人的一轮轮 401。
5. 把代码讲透
5.1 payload 构造层:状态机把 kit 的规矩焊死
三条场景状态机(外卖 5 步、打车 6 步、比分 5 步)都在 liveViewPayload.ts,纯函数 step -> spec。两条 kit 规矩由基类持有:
// liveViewPayload.ts(节选)
export class ScenarioMachine {
private sequence = 0;
/** Monotonic: start gets 1, every update bumps by one. */
nextSequence(): number { return ++this.sequence; }
}
打车场景最能体现"一个场景多种模板":呼叫段是 PickupLayout(强调"等待司机接单")+ TimerCapsule(呼叫计时),接单段切到车牌强调 + TextCapsule(车牌 + 距离),行程段再切 ProgressLayout + ProgressCapsule——胶囊与扩展区模板的切换就发生在步骤推进里,全程只是改 spec 字段,桥和 kit 都感知不到"切换"这回事。
vitest 的锚定点不在"能构造出来",而在字段值逐个对——expect(layout.content).toBe('京A·8P9X2')、expect(capsule.title).toBe('2:1')、比分的 hostScore 必须是 string 不是 number。桥对面是逐字段装配,这边少校验一个字段,那边就渲染不出来。
外卖场景的构造最能说明"字段随步骤流动"的设计——进度值、富文本两行、辅助区文案、胶囊文案全部从步骤表驱动,模板与胶囊形态全程不变:
// liveViewPayload.ts - DeliveryScenario.specFor(节选)
override specFor(step: number): LiveViewSpecJson {
const last = step === this.stepCount - 1;
return {
id: this.id, event: this.event, subEvent: this.subEvent,
sequence: this.nextSequence(), isMute: this.isMute,
shareUrl: this.shareUrl,
lifeCycleMode: LifeCycleMode.AUTO_STOP_WHEN_APP_TERMINATE,
liveViewData: {
primary: {
title: DELIVERY_TITLES[step],
content: [
{ text: DELIVERY_CONTENT[step]?.[0] ?? '' },
{ text: DELIVERY_CONTENT[step]?.[1] ?? '' },
],
keepTime: last ? 600 : undefined, // 送达后归档 10 分钟
extensionData: { type: ExtensionType.COMMON_TEXT, text: DELIVERY_EXT[step] },
layoutData: {
layoutType: LayoutType.PROGRESS,
progress: DELIVERY_PROGRESS[step] ?? 0, // 10 → 25 → 60 → 85 → 100
color: '#FF007DFF', backgroundColor: '#19000000',
lineType: last ? 1 : 0,
},
},
capsule: {
type: CapsuleType.PROGRESS, status: 1,
progress: DELIVERY_PROGRESS[step] ?? 0, max: 100,
content: DELIVERY_CAPSULE[step],
},
},
};
}
比分的胶囊有个专门的设计点:标题传"数字:数字"('1:0'、'2:1'),6.0.0(20) 起 kit 会自动提取两侧数字渲染成队徽样式——payload 层只保证标题与 hostScore/guestScore 逐字一致(vitest 里两者锁死在同一个测试里),样式的事交给系统。
5.2 ArkTS 装配器:字符串进,typed 对象出
specFromJson 与 Flutter 成员的 LiveViewCodec 同构:解析 JSON 后按胶囊类型(TEXT 1 / TIMER 2 / PROGRESS 3)与扩展区模板(PROGRESS 3 / PICKUP 4 / FLIGHT 5 / SCORE 7)分支装配,可选字段条件赋值。运行时契约的注入也在这一层:
// LiveViewModule.ets(节选)
const agent = await this.hostClickAction(); // wantAgent(运行时必传)
if (agent !== null && spec.liveViewData.primary.clickAction === undefined) {
spec.liveViewData.primary.clickAction = agent;
}
比分模板的装配是四个分支里字段最多的——注意每个字段的类型都要与 kit 的 d.ts 对齐(比分是 string、descPic 是 string|PixelMap):
// LiveViewModule.ets(节选)
} else if (layType === liveViewManager.LayoutType.LAYOUT_TYPE_SCORE) {
const score: liveViewManager.ScoreLayout = {
layoutType: liveViewManager.LayoutType.LAYOUT_TYPE_SCORE,
hostName: str(layRec, 'hostName'),
hostScore: str(layRec, 'hostScore'), // string,不是 number
guestName: str(layRec, 'guestName'),
guestScore: str(layRec, 'guestScore'),
competitionDesc: str(layRec, 'competitionDesc'),
competitionTime: str(layRec, 'competitionTime'),
isHorizontalLineDisplayed: bool(layRec, 'isHorizontalLineDisplayed', true)
};
layoutData = score;
}
hostClickAction 用 uiAbilityContext.applicationInfo.name 拿宿主包名(注意:ApplicationInfo 上没有 bundleName 属性,bundle 名在 name 里),wantAgent.getWantAgent 只有 Promise 版——整个 publish 因此是 async 链,别想着同步拿。publish 的流程只有三步:装配、注入、调用,失败在每一步都被转成结构化结果:
// LiveViewModule.ets(节选)
private async publish(op: string, specJson: string): Promise<Object> {
let id = 0, sequence = 0;
try {
const spec = specFromJson(specJson);
id = spec.id; sequence = spec.sequence ?? 0;
const agent = await this.hostClickAction();
if (agent !== null && spec.liveViewData.primary.clickAction === undefined) {
spec.liveViewData.primary.clickAction = agent;
}
// start / update / stop 分派到 kit
const r = await (op === 'start'
? liveViewManager.startLiveView(spec)
: op === 'update'
? liveViewManager.updateLiveView(spec)
: liveViewManager.stopLiveView(spec));
const payload = this.outcome(op, id, sequence, r.resultCode, `${r.message}`);
this.emit(payload); // 事件通道(Record 摊平)
return payload; // Promise 回包(双通道之一)
} catch (e) { /* 同款结构化失败 */ }
}
几个调试时才意识到的地方:
Promise<Object> 不能返回 null。 getActiveLiveView 的 catch 里写 return null 直接编译错(Type 'null' is not assignable to type 'Object')——返回空串,JS 侧按"无在册实况窗"理解。
Publish 的业务失败走正常回包,不走异常。 kit 对"胶囊更新失败"这类业务失败返回 resultCode != 0,桥把它们原样回传 JS(resolve 而不是 reject)——调用方拿到结构化结果自己决定怎么提示,桥不吞错也不抛错。
5.3 事件通道:统一用 Record,Map 会变成 {}
发布结果除了 Promise 回包,还会经 emitDeviceEvent('onLiveViewEvent', record) 推给 JS(日志页的实时流水就是它)。这个问题单独说:RNOH 事件通道把 ArkTS Map 序列化成 {}——所以模块侧手工把字段摊平成 Record:
// LiveViewModule.ets(节选)
private emit(payload: Record<string, Object | null>): void {
const record: Record<string, Object | null> = {
'type': 'publish',
'op': payload['op'],
'id': payload['id'],
// ... 全部摊平
};
this.context.rnInstance.emitDeviceEvent('onLiveViewEvent', record);
}
JS 侧的 publish 与解码也一并放在这里——注意 catch 分支:桥不可达(非鸿蒙平台)时构造结构化的失败结果而不是抛出,调用方拿到的永远是可渲染的对象:
// useLiveView.ts(节选)
const publish = async (op, snap): Promise<PublishOutcome> => {
console.log(`LVK-JS publish ${op} seq=${snap.spec.sequence}`); // hilog 逐跳打点
const specJson = JSON.stringify(snap.spec);
try {
const raw = (await fn.call(NativeLiveView, specJson)) as Record<string, unknown>;
return decodePublishOutcome(raw) ?? { ...结构化失败... };
} catch (e) {
return { op, id: snap.spec.id, sequence: snap.spec.sequence,
resultCode: -1, message: `${e}` };
}
};
decodePublishOutcome 对未知 op 返回 null——宁可丢一条日志,也不让坏数据进 UI 状态。
这条双通道还有个隐性收益:日志页与业务页面解耦。日志页只消费事件流,业务页只消费 Promise——谁也不依赖谁的挂载时机。冷启动探针那类"回包可能迟到"的场景由 probe 的宽松解码单独兜住,三条互不拖累。这条规则和 audio 轮的教训一字不差地复用:跨端桥序列化规则两端各验一次,别假设对称。
5.4 颜色字节序:kit 的 #AARRGGBB 到了 RN 要换座
kit 的颜色是 #AARRGGBB(蓝图色 #FF007DFF),RN 的 8 位 hex 解析成 #RRGGBBAA——同一个字符串在 RN 里渲染成粉红。App.tsx 里一个 10 行函数做字节序交换:
function toRgba(argb: string): string {
if (argb.length === 9 && argb.startsWith('#')) {
return `#${argb.slice(3)}${argb.slice(1, 3)}`;
}
return argb;
}
进度条颜色只用了一次 bundle 重建就改回来了。跨端颜色字节序,又一条要写进规约。
5.5 应用内实验室:四个组件撑起一页
App.tsx 的结构刻意保持薄——所有业务判断都在 payload 层与 hook 里,组件只做两件事:按 spec 渲染、把交互转成 publish 调用。
CapsulePill:胶囊三分支渲染(Text 主/副文本、Timer 时钟、Progress 迷你比例条),与 kit 的三种CapsuleType一一对应;CardPreview:卡片三区(固定/辅助/扩展),扩展区按layoutType分派ProgressArea / PickupArea / ScoreArea三个子组件——比分的三栏布局(主队 / 中轴赛事信息 / 客队)就是一个十几行的 flex 行;SwipeShareCard:PanResponder 驱动Animated.Value位移,露出底层绿色分享面板,-55px 阈值触发onShared(shareUrl)后弹簧回弹;ScenarioLab:状态机实例 + 步骤状态 +publish调用的编排层,busyref 防重入(上一个 publish 未决时忽略新点击)。
日志页直接消费 lv.publishLog——每条流水是 decodePublishOutcome 产出的结构化对象,绿 0 红 非0。整个实验室的组件没有一处直接摸 NativeModules:组件层只按 spec 渲染,逻辑都留在 hook 和 payload 层。
进入第 6 节之前,先把 hook 的代码放在这里——它是"订阅 + 探针 + 降级"三段式结构的完整样本:
// useLiveView.ts(节选)
useEffect(() => {
mounted.current = true;
const sub = DeviceEventEmitter.addListener(EVENT_NAME, (payload) => {
const outcome = decodePublishOutcome(payload as Record<string, unknown>);
if (outcome) pushLog(`${outcome.op} #${outcome.sequence} · resultCode ${outcome.resultCode}`, outcome.resultCode === 0);
});
const hasBridge = NativeModules.LiveView !== undefined;
if (hasBridge) {
void refresh(); // probe:native 回包落地则徽章转绿
} else {
pushLog('无原生桥 · 预览模式(非鸿蒙平台)', false);
}
return () => { mounted.current = false; sub.remove(); };
}, []);
除实验室之外,还有一份容易被忽略的交付物:宿主即模板。example/harmony 是一个完整的、在本轮真实编译通过的 RNOH 工程——ffrt 补丁、空壳 generated 包头、手写 JSI 胶水、四步接线的 RNPackagesFactory,全部原样在里面。任何"RN 库 + 鸿蒙系统能力"的新项目,把这棵目录树拷过去改名,能省掉一个下午的踩坑时间。
6. 我踩过的坑(真实报错与现场记录)
这一节全是坑,以下来自真实的报错与现场记录。
坑一:descPic 运行时必传。
Parameter error. The type of layoutData.descPic must be string | image.PixelMap [or the parameter is mandatory].
首次打车发布暴露的——PickupLayout 右侧的商品描述图也是"d.ts optional、运行时 mandatory"家族的一员(同族还有 clickAction / nodeIcons / capsule.icon / capsule.backgroundColor,Flutter 成员的 verification.md 里已记四条)。默认注入 lv_node_a.png 后归零。
坑二:红屏 “has not been registered”。
Invariant Violation: "SpatialAudioRNExample" has not been registered.
宿主 Index.ets 里 RNApp 的 appKey 忘了随库改名——JS 侧注册的是 LiveViewRNExample,ArkTS 侧按旧名字找。模板拷贝之后,名字要全局搜一遍。
坑三:RNOHGeneratedPackage.h file not found。
PackageProvider.cpp:2:10: fatal error: 'generated/RNOHGeneratedPackage.h' file not found
codegen 没跑(独立工程跑不起来),PackageProvider 的硬包含就炸了。宿主没有自己的 codegen spec 时,手写一个空壳包头即可——这本来就是"generated"语义的合法退化。
坑四:方法表漏项 = 命令永远 pending。 这是 audio 轮的老坑,本轮再次确认:methodMap_ 里少登记一个方法,JS 侧那个 Promise 就永远悬着,无报错、无日志。本轮所有发布按钮"点了没反应"的排查都该先查它。
坑五:RN 把 #AARRGGBB 当 #RRGGBBAA。 蓝色进度条变粉红(5.4 节)。类型系统管不了颜色字节序。
坑六:RN 页面顶进状态栏。 默认布局的 header 会被系统时间压住,paddingTop: 48 的安全区 padding 是截图能见人的前提。
坑七:metro 出包的时机。 bundle.harmony.js 必须在 index.js / App.tsx 定稿之后重新生成——旧 bundle 进新 HAP,红屏和旧文案会一起回来。每次改 JS 后的固定三连:bundle → assembleHap → 卸载重装。
坑八:坐标会漂。 uitest 自动化点击前必须重新 dumpLayout——换 Tab、换页面、加安全区 padding 都会让按钮位置偏移几像素到几十像素,差 3px 就点空。本轮"发布按钮点了没反应"的真相之一,就是点在了按钮上方 3px 的空白处。
坑九:宿主改名的三处联动。 从模板库改名成 live-view-rn 时,example/harmony/build-profile.json5 的模块名与 srcPath、entry/oh-package.json5 的依赖名与路径、harmony/rn_live_view 自身的 build-profile.json5(缺它报 Can not find build config file)——三处文件少改一处,ohpm/hvigor 就会拿着旧路径找文件,报错文本只提最后一跳。
坑十:Promise 挂起会让交互整页假死。 实验室里 busy ref 挡住重入点击——一旦某个 publish 的 Promise 永不落定(桥初始化期的竞态、方法表漏项),整页按钮就全都不响应且没有任何报错。防御两手:hook 里给每个 publish 套超时兜底(超时构造结构化失败结果),方法表与 spec 的同步纳入 code review 清单。"永远 pending"比"立刻报错"难查得多。
坑十一:metro 出包前的"缓存三查"。 bundle 内容不对(旧文案、旧包名)时按顺序查三处:example/index.js 的注册名、rawfile 里 bundle.harmony.js 的 mtime、metro 的启动 cwd(不对会解析到另一份依赖树)。三查之后再考虑别的。
坑十二:install 期的 prepare 会跑 build。 package.json 的 prepare: npm run build 让每次 npm install 都重跑 babel/types——payload 层有 TS 错误时,装依赖都会失败(npm error command failed ... npm run build),报错位置离根因十万八千里。依赖一条规则:改完 TS 先 npm run typecheck,别让 install 当你的编译器。
7. 现在怎么用:从 三方库 到依赖
三件套的分工表放在这里,选型时对照:
| 成员 | 桥接 | payload 层 | 系统发布 | 预览器 |
|---|---|---|---|---|
| flutter_live_view | MethodChannel + EventChannel 全桥接 | Dart 状态机 | ✅ 实测 resultCode 0 | Flutter 自绘 |
| live-view-rn(本库) | AnyThreadTurboModule + 手写 JSI 胶水 | 纯 TS 构造层 | ✅ 同 kit,链路逐跳验证 | RN 组件 |
| live-view-cordova | 零原生(沙箱如实) | 纯 JS 构造层 | ❌ 沙箱不可达 | DOM 渲染器 |
npm 形态,file / git 依赖直接用:
npm install ../live-view-rn
# 或
npm install git+https://atomgit.com/oh-react-native/live-view-rn.git
完整 API 表、宿主接线四步、排错清单在三库共通的文档里:本库的技术路线分工、结构与构建核对、实测记录与坑清单;测量原始数据也放在仓库里。三库对照的系列总览在实况窗系列总览里。
权限这件事要说清楚:实况窗按场景受控开放(TAXI / DELIVERY / SCORE 等,
AGC 按场景申请)。这次的调试包在模拟器上未申请权限也拿到了 enabled=true
——调试链路宽松;真机分发前请把场景权限办下来。应用侧要做的只有两件事:
probe() 的结果如实展示(系统页就是现成的调试面板),以及被用户拒绝后
不再反复重试发布——实况窗是用户授权制,骚扰式重试只会换来第二次拒绝。
下一步:TimerCapsule 的 countdownPreset(呼叫超时自动换文案)、
CustomLayout(26.0.0 自定义扩展区)、地理围栏触发(startLiveViewByTrigger)。
payload 构造层是纯 TS——新字段加进 types 与状态机,vitest 锚一轮,桥的
装配器补一段分支,三处改完这条链路就长了一截。
最后附上屏自检清单——本文所有环节的浓缩,接手的人按这六条走一遍,
链路是否健康一目了然:
probe()三值如实展示(present / enabled / detail),徽章不做假;- JS→ArkTS 逐跳 hilog 留痕(
LVK-JS calling native→publish entered
→start id=),单跳 2ms 量级; - start / update / stop 全链路 resultCode 0,日志页流水与 hilog 一致;
- 胶囊三种形态(文本 / 计时 / 进度)与卡片三类模板(进度 / 强调 / 比分)
预览逐一切过; - 左滑分享交互可用,
shareUrl为 HTTPS 且 <128 字符; - 非鸿蒙平台打开时降级为"预览模式",无白屏无崩溃。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)