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 Studio26.0.0.851(HarmonyOS SDK 26.0.0 Release / API 26)
React Native0.84.1(Hermes,release minified bundle)
RNOH0.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 库接鸿蒙系统能力的通用姿势):

  1. oh-package.json5 加依赖:"@rnoh/live-view-rn": "file:../../../harmony/rn_live_view";
  2. RNPackagesFactory.ets:return [new LiveViewPackage(ctx)];
  3. cpp 胶水:LiveViewPackage.h(方法表)+ PackageProvider.cpp 里 make_shared;
  4. 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.PixelMaplv_node_a.png
capsule.icon胶囊must be string | image.PixelMaplv_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 调用的编排层,busy ref 防重入(上一个 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_viewMethodChannel + EventChannel 全桥接Dart 状态机✅ 实测 resultCode 0Flutter 自绘
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 锚一轮,桥的
装配器补一段分支,三处改完这条链路就长了一截。

最后附上屏自检清单——本文所有环节的浓缩,接手的人按这六条走一遍,
链路是否健康一目了然:

  1. probe() 三值如实展示(present / enabled / detail),徽章不做假;
  2. JS→ArkTS 逐跳 hilog 留痕(LVK-JS calling native → publish entered
    → start id=),单跳 2ms 量级;
  3. start / update / stop 全链路 resultCode 0,日志页流水与 hilog 一致;
  4. 胶囊三种形态(文本 / 计时 / 进度)与卡片三类模板(进度 / 强调 / 比分)
    预览逐一切过;
  5. 左滑分享交互可用,shareUrl 为 HTTPS 且 <128 字符;
  6. 非鸿蒙平台打开时降级为"预览模式",无白屏无崩溃。
Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐