React Native 鸿蒙实况窗实战:基于 RNOH TurboModule 封装 LiveViewKit,打通外卖、打车、比分场景,详解 sequence 驱动锁屏倒计时、对象式停止接口
示例仓库:https://atomgit.com/dijun_520/react-native-ohos-live-view
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-RN/ohos_react_native/tree/0.84-main
CPF-RN 鸿蒙社区:https://atomgit.com/CPF-rn
0. 环境与实测设备
| 项目 | 版本 |
|---|---|
| 开发工具 | DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk) |
| 系统 API | HarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0) |
| React Native | 0.84.1 |
| RN 鸿蒙框架 | @react-native-oh/react-native-harmony 0.84.5(RNOH) |
| Node.js | ≥ 22.11.0 |
| 实测设备 | 华为(nova 14) |
1. “实况窗就是个通知”
接到这个题的时候,我第一反应是:实况窗嘛,不就是一条常驻通知,加个进度条?
我一开始也以为它只是"系统帮我挂一条横幅,我把文案塞进去,剩下的交给通知系统"。这个理解撑了我大概二十分钟——直到我把 @hms.core.liveview.liveViewManager.d.ts(SDK 2996 行)从头翻到尾,看到的是另一番景象:
// @hms.core.liveview.liveViewManager.d.ts(去注释后的关键签名)
function isLiveViewEnabled(): Promise<boolean>;
function startLiveView(liveView: LiveView): Promise<LiveViewResult>;
function updateLiveView(liveView: LiveView): Promise<LiveViewResult>;
function stopLiveView(liveView: LiveView): Promise<LiveViewResult>; // ← 注意参数
function getActiveLiveView(id: number): Promise<LiveView>;
三个细节立刻推翻了我的朴素理解:
stopLiveView的参数是LiveView对象,不是 id。一个"停止"接口不收 id 收全量对象,说明系统侧根本不打算让你"随手关一个"。- 返回值是
LiveViewResult { resultCode, message },每个动作都有独立的结果码,不是成功/失败两态。 LiveView上层字段里躺着timer、sequence、lifeCycleMode、subEvent、shareUrl——锁屏上的动态倒计时、乐观更新的版本号、应用退出是否自动结束,全是系统能力。
所以这个题目的边界很清楚:在 React Native(RNOH)里把 LiveViewKit 封装成一个 TurboModule 三方库,把 LiveView 对象翻译成 JS 可构造的普通对象,把锁屏、胶囊、卡片的数据流和左滑分享的手势流都带回 RN 世界。
拆下来是三件事:
- 把 JS 侧的场景数据(外卖/打车/比分)翻译成 ArkTS 侧的结构体,喂给
liveViewManager; - 把原生结果与错误(
resultCode、BusinessError)用事件流回传给 JS; - 在系统实况窗不可用的环境(模拟器、无权益)提供应用内模拟预览,让数据流照样能跑通。
2. 效果展示

这是 example 工程的首页。这里每一行都不是装饰:
- 顶部状态行的「系统实况窗可用/不可用」来自
isLiveViewEnabled()的返回——模拟器上返回false,因为模拟器没有华为账号和实况窗权益; - 中间的卡片是应用内模拟预览,数据结构与系统实况窗完全同源(
title、content富文本、layoutData.progress、timer),所以系统侧不可用的时候,RN 侧的数据流照样一帧不差地跑; - 底部事件日志里每一行对应一次原生回调:
start(code)、update(code)、stopped、error,来自 ArkTS 侧emitDeviceEvent('onLiveViewEvent', ...)。

胶囊态模拟的是状态栏胶囊:左边圆点是场景色(外卖橙、打车蓝、比分绿),标题后面跟着 content 字段。真实设备上这个胶囊由系统绘制在状态栏里,应用内预览只是同数据、不同画笔。

锁屏态预览加了系统时钟和日期,卡片布局与真实锁屏实况窗一致。真机上要做到沉浸式锁屏卡片,还要配合 liveViewLockScreen 类型的 ExtensionAbility。
主动交代边界:以上截图全部来自模拟器(系统实况窗能力返回不可用),应用内预览承担了展示职责;系统实况窗(真正的锁屏/状态栏胶囊)需要登录华为账号、打开实况窗开关、且应用具备实况窗权益的真机才能看到。
2.1 真机实拍:三态同览 + 全链路日志
后来我把 example 装上了真机(HUAWEI TLR-AL00,HarmonyOS 7.0.0.111)。真机版首页把三个状态同时摆出来,并且每个预览都按华为对三态的定义来还原形态,而不是三张同源的截图换个背景色:
- 胶囊态:应用退后台后,状态栏里的一条窄小胶囊——极简只放任务状态(“骑手已取餐”)和倒计时(28:00),和信号、电量挤在同一行,点击展开卡片;
- 卡片态:点击胶囊 / 通知中心下拉后弹出的实况卡片——图标、标题、倒计时、进度模板俱全,底部带交互按钮(查看配送 / 联系骑手),是实况窗的主交互形态;
- 锁屏态:锁屏界面直接渲染的沉浸卡片——深色底 + 系统时钟 + 日期,不用解锁就能看、点按钮直接操作。

锁屏态特写——深色沉浸卡片同样带交互按钮,“上滑解锁 · 卡片免解锁可看可点”:

卡片底部那两个按钮不是预览画出来的装饰。LiveViewKit 从 5.1.1(19) 起在扩展区 LayoutData 上提供了 serviceButtons(最多 3 个,每个可挂 WantAgent 跳转)和 isServiceButtonsDisplayed 开关,库把 JS 侧 primary.serviceButtons 一并映射了进去——真机的系统卡片会据此渲染同样的按钮。这里埋着一个文档不太提的坑:系统默认 isServiceButtonsDisplayed=false,不显式置 true,按钮压根不出现;而且按钮挂在扩展区布局上,卡片没配 layoutData 时按钮也不会渲染。

安装启动入口页(系统实况窗能力探测返回可用,说明真机的华为账号与实况窗开关都是就绪的):

3. 原理:LiveViewKit 到底替你画了什么
先给全文最重要的模型判断:实况窗不是应用画的,是系统画的——应用交数据,不交 UI。 给系统的 LiveView 对象里只有文案、颜色值、进度数字和模板枚举,锁屏上那张卡片、状态栏那颗胶囊,全是系统按场景模板(event + LayoutType)渲染的。这就是为什么它的数据结构里没有一个"View"字段,全是"Data"字段。
第二个判断:胶囊和卡片是同一份数据的两种投影。 LiveViewData 里 primary 是卡片数据,capsule 是胶囊数据,timer 是两者共享的动态时间。你更新一次,系统同时刷新锁屏卡片、状态栏胶囊、通知面板三处。不是三条链路,是一条链路的三个出口。
把系统的入口和回调整理成表:
| 接口/事件 | 方向 | 参数 | 应用要回答什么 |
|---|---|---|---|
isLiveViewEnabled() | JS/ArkTS → 系统 | 无 | 能力是否开启(账号/开关/权益) |
startLiveView(liveView) | 应用 → 系统 | 完整 LiveView | 首屏数据:primary + capsule(+timer) |
updateLiveView(liveView) | 应用 → 系统 | 完整 LiveView(sequence+1) | 新一帧数据,全量替换 |
stopLiveView(liveView) | 应用 → 系统 | 创建时的 LiveView 对象 | 你还记得这个实况窗吗 |
onLiveViewEvent(本库事件) | ArkTS → JS | {type, liveViewId, code, message} | RN 侧更新日志与状态 |
liveViewLockScreenAbilityName | 应用 → 系统 | ExtensionAbility 名 | 锁屏沉浸卡片由谁渲染 |
两个细节决定了后面所有的降级逻辑:
event是场景路由键(DELIVERY/TAXI/SPORTS_GAME/TIMER……),系统按场景挑模板、按场景决定锁屏展示策略,乱传事件类型系统不报错但展示会退化;updateLiveView是全量替换,不是增量 patch——RN 侧每次状态变化都要重发整个LiveView,sequence递增只是给系统一个排序依据。
4. 工程怎么搭
这次整理最关键的变化,是把"能跑"变成"能复用":JS 接口、ArkTS 实现、示例工程三件事拆进三个目录,互相只通过公共边界说话。
react-native-ohos-live-view/
├── src/ # 跨端 JS/TS 源码(npm 包入口)
│ ├── NativeLiveView.ts # Codegen Spec:TurboModule 规范声明
│ ├── LiveView.ts # API 门面:start/update/stop/shareCard/addEventListener
│ ├── useLiveView.ts # 生命周期 Hook(创建→更新→停止→分享)
│ ├── scenes.ts # 预置场景构造器:外卖/打车/比分
│ └── types.ts # LiveViewConfig 等类型(对齐 ArkTS 侧)
├── harmony/ # 鸿蒙 HAR 三方库
│ ├── build-profile.json5 # apiType stageMode(HAR 模块)
│ ├── index.ets # HAR 导出入口
│ └── src/main/ets/
│ ├── LiveViewModule.ts # TurboModule:LiveViewKit + ShareKit 封装
│ ├── LiveViewPackage.ts # RNOH 包注册(RNPackage/TurboModulesFactory)
│ └── LiveViewTypes.ts # ArkTS 侧类型
├── build-profile.json5 # HAR 工程根(hvigor 编 HAR 用)
├── AppScope/app.json5
└── example/
├── App.tsx # 三场景 + 事件日志 + 生命周期控制
├── src/LiveViewSimulator.tsx # 应用内实况窗模拟预览(胶囊/卡片/锁屏 + 左滑手势)
└── harmony/ # 示例鸿蒙壳工程
├── entry/src/main/cpp/CMakeLists.txt # 产出 librnoh_app.so
└── entry/libs/react-native-ohos-live-view.har # 三方库 HAR
三条边界:src/ 不依赖任何页面,只出 API 与 Hook;harmony/ 不感知 RN 组件,只做 TurboModule;example/ 只走公共 API,不绕过封装直接摸原生。
JS 侧最小接入(15 行):
// example/App.tsx - 三步:探能力 → 启动 → 听流
import { useLiveView, createDeliveryLiveView } from 'react-native-ohos-live-view';
const { systemEnabled, start, update, stop, shareCard } = useLiveView();
// 探能力
if (systemEnabled) { /* 系统实况窗可用 */ }
// 启动:锁屏、胶囊、卡片同步生效
await start(createDeliveryLiveView({
id: 1001, stageTitle: '骑手配送中', stageDesc: '骑手已取餐',
progress: 60, etaMinutes: 15,
}));
// 听流
useLiveView(); // 内部已挂 onLiveViewEvent
通道协议就是 TurboModule 方法 + DeviceEventEmitter 事件两条线。JS → ArkTS 的 LiveViewConfig 是纯 JSON 对象;ArkTS → JS 的事件是一行:
{ "type": "updated", "liveViewId": 1001, "code": 0, "message": "" }
两个容易被忽略的窗口期:
start的 Promise 还没 resolve、addEventListener还没到达平台——这个窗口里系统已经可能回错(比如权益校验失败)。ArkTS 侧emitEvent不依赖 JS 先订阅,事件由DeviceEventEmitter缓冲分发;- 场景状态机推进到"已送达"时,
update和stop可能竞态。example 里用running状态位收敛:先setRunning(false)再stop(),update的 effect 只在running === true时触发。
5. 把代码讲透
5.1 能力探测:isLiveViewEnabled() 的三种 false
// harmony/src/main/ets/LiveViewModule.ts - isLiveViewEnabled()
isLiveViewEnabled(): Promise<boolean> {
return liveViewManager.isLiveViewEnabled().catch((err: BusinessError) => {
hilog.error(DOMAIN, TAG, `isLiveViewEnabled failed: %{public}d %{public}s`, err.code, err.message);
this.emitEvent('error', -1, err.code, err.message);
return false;
});
}
三个细节值得单独说:
第一,false 不区分原因。 官方文档说它返回 false 时可能是没登录华为账号、开关被关、或者应用没有实况窗权益,接口本身不告诉你哪种。我们把 BusinessError 的 code 通过事件带回 JS。
第二,模拟器必然 false。 模拟器没有华为账号体系,这一步就拦住了。所以 example 把 systemEnabled 显示在顶栏。
第三,Platform.OS === 'harmonyos' 在 TS 类型里不存在。 RNOH 运行时注入 'harmonyos',但 RN 的类型声明只有 ios/android 等。直接比较 TS 会报 no overlap,得写成 (Platform.OS as string) === 'harmonyos'——这是所有 RNOH 库都绕不开的一行。
5.2 创建:把 JS 对象翻译成系统模板
// harmony/src/main/ets/LiveViewModule.ts - toSystemLiveView()(节选)
const primaryData: liveViewManager.PrimaryData = {
title: primary.title,
content: content, // Array<RichText>,不是 string
keepTime: primary.keepTime ?? 0,
};
...
const liveView: liveViewManager.LiveView = {
id: config.id,
event: config.event,
sequence: config.sequence ?? 1,
isMute: config.isMute ?? false,
liveViewData: liveViewData, // { primary, capsule }
};
if (config.timer) {
liveView.timer = { time: config.timer.time,
isCountdown: config.timer.isCountdown ?? false,
isPaused: config.timer.isPaused ?? false };
}
三个细节值得单独说:
第一,胶囊是三选一,不是一个对象。 capsule 字段的类型是 TextCapsule | TimerCapsule | ProgressCapsule,文本胶囊有 title/content,计时胶囊有 time/isCountdown,进度胶囊有 progress/max。JS 侧传 type: 'CAPSULE_TYPE_TEXT' | 'CAPSULE_TYPE_TIMER' | 'CAPSULE_TYPE_PROGRESS',ArkTS 侧按类型分别构造——这里是整个转换器里分支最多的地方。
第二,LayoutType 是数值枚举。 LAYOUT_TYPE_PROGRESS = 3、LAYOUT_TYPE_SCORE = 7、LAYOUT_TYPE_PICKUP = 4。JS 侧传字符串,ArkTS 侧 switch 成枚举再构造成对应的 ProgressLayout | ScoreLayout | PickupLayout。比分模板字段名是 hostScore/guestScore(主队/客队),不是 home/away——名字对不上系统不报错,比分显示成 0:0。
第三,锁屏沉浸卡片是可选挂载。 PrimaryData.liveViewLockScreenAbilityName 指向宿主应用里声明为 liveViewLockScreen 类型的 ExtensionAbility,系统锁屏时拉起它渲染自定义锁屏卡片。
一个反直觉陷阱:不能用 resultCode 之外的任何字段判断成功。LiveViewResult 只有 resultCode 和 message,没有 id 回传、没有句柄。
5.3 更新:sequence 驱动的全量替换
// example/App.tsx - 场景状态机(节选)
const config: LiveViewConfig | null = useMemo(() => {
sequenceRef.current += 1; // 每次重建 +1
if (tab === 'delivery') {
return createDeliveryLiveView({
id: LIVE_VIEW_ID,
stageTitle: DELIVERY_STAGES[delivery.stageIndex],
progress: Math.min(100, delivery.stageIndex * 30 + (delivery.eta < 10 ? 15 : 5)),
etaMinutes: delivery.eta,
});
}
...
}, [tab, delivery, taxi, score]);
useEffect(() => {
if (!running) return;
const cfg = { ...config, sequence: sequenceRef.current };
update(cfg); // 全量替换
}, [config, running]);
外卖场景的状态机是 商家接单 → 骑手取餐 → 配送中 → 已送达 四阶段,setInterval 每 3 秒推一格;打车是 呼叫 → 已接单 → 已到达,倒计时归零触发到达;比分是比赛时钟每 3 秒 +3,进球事件按 clock % 15 模拟。三个场景共用一条"状态 → config → update"的单向流。
倒计时这件事有个容易写错的点:timer.time 是毫秒,isCountdown: true 时系统在锁屏和胶囊上自动倒数显示。
5.4 停止:stopLiveView(liveView) 的对象缓存
// harmony/src/main/ets/LiveViewModule.ts - stopLiveView()(节选)
private liveViewCache: Map<number, liveViewManager.LiveView> = new Map();
async stopLiveView(liveViewId: number): Promise<boolean> {
const cached = this.liveViewCache.get(liveViewId);
const liveViewObj: liveViewManager.LiveView = cached ?? {
id: liveViewId,
event: 'TIMER',
liveViewData: { primary: { title: '' } },
};
const result = await liveViewManager.stopLiveView(liveViewObj);
...
}
这里有一个很容易被忽略的窗口期:start 成功后 ArkTS 侧把 LiveView 对象按 id 缓存进 Map,stop 时原样交还系统。为什么必须缓存? 因为官方签名收的是对象,而 JS 侧只有 id。系统拿这个对象做什么没写在文档里(大概率是校验 id 与 event 的对应关系),但拿一个伪造的空对象去 stop,模拟器上 resultCode 会给非 0。
降级说明:RN 侧热重载(Metro reload)会重建 TurboModule,Map 随实例销毁,此时 stop 只能拿到兜底对象。
5.5 左滑分享:从 RN 手势到 ShareKit
// example/src/LiveViewSimulator.tsx - 左滑手势(节选)
const panResponder = useRef(
PanResponder.create({
onMoveShouldSetPanResponder: (_e, g) =>
Math.abs(g.dx) > 12 && Math.abs(g.dy) < 32,
onPanResponderRelease: (_e, g) => {
if (g.dx < -50) swipeLeftRef.current?.();
},
}),
).current;
// harmony/src/main/ets/LiveViewModule.ts - shareLiveViewCard()(节选)
const record: systemShare.SharedRecord = {
utd: uniformTypeDescriptor.UniformDataType.PLAIN_TEXT,
title: jsData.title,
content: jsData.summary,
description: '来自鸿蒙实况窗卡片',
};
const sharedData: systemShare.SharedData = new systemShare.SharedData(record);
const controller: systemShare.ShareController = new systemShare.ShareController(sharedData);
await controller.show(uiCtx, {
selectionMode: systemShare.SelectionMode.SINGLE,
previewMode: systemShare.SharePreviewMode.DEFAULT,
});
三个细节值得单独说:
第一,"左滑分享"是应用内手势,不是系统手势。 系统实况窗卡片本身没有暴露"左滑"回调——所以我们在 RN 的模拟卡片上挂 PanResponder,横向位移超过阈值就调原生 shareLiveViewCard,把卡片当前内容(标题 + 富文本拼接)交给 ShareKit。手势是 RN 的,分享面板是系统的,两层各管各的。
第二,SharedData 构造函数只收一个 SharedRecord。 我一开始照着旧文档传 { records: [...] },ArkTS 编译器直接报 Argument of type '{ records: ... }' is not assignable to parameter of type 'SharedRecord'。新 SDK 是"构造时单条、addRecord 加多条"。
第三,controller.show(context, options) 不是 showShareSheet。 旧 API 名在新 SDK 里不存在,编译期就会暴露——这反而是 ArkTS 严格类型的好处,iOS/Android 侧同类问题往往要到运行时才炸。
回调链是:JS PanResponder → TurboModule shareLiveViewCard → ShareKit 系统面板 → 用户操作 → Promise resolve → emitEvent → JS 日志。任何一环失败都落到 error 事件,日志面板可见。
6. 踩坑与经验
坑一:file: 源码目录依赖,ohpm 装得上、hvigor 编不过。 最初 example 的 entry/oh-package.json5 用 "react-native-ohos-live-view": "file:../../../harmony" 直连库源码目录,ohpm 正常安装(在 entry/oh_modules 下生成符号链接),构建却在 ArkTS 编译阶段报:
Error Message: Failed to resolve OhmUrl. Failed to get a resolved OhmUrl for
"/Users/.../react-native-ohos-live-view/harmony/index.ets" imported by
".../entry/src/main/ets/pages/Index.ets".
排查了一圈才反应过来:hvigor 只为工程内注册的模块生成 OhmUrl,符号链接指到工程外,编译器根本不把它当构建单元。正确做法是把库编成 HAR,让 example 依赖 file:../libs/react-native-ohos-live-view.har。
坑二:HAR 工程的 module.json5 名字不允许连字符。 编 HAR 时报:
Schema validate failed ... instancePath: 'module.name', keyword: 'pattern',
params: { pattern: '^[a-zA-Z][0-9a-zA-Z_.]*$' }
模块名只能是字母数字下划线点,react-native-ohos-live-view 过不了校验。最终模块名叫 react_native_ohos_live_view,ohpm 包名保持 react-native-ohos-live-view——**npm 包名和 HAR 模块名是两套命名空间。
坑三:根 build-profile.json5 里多写了一个 modelVersion。 hvigor 6 的工程根 profile 只接受 app 和 modules 两个顶层键:
Schema validate failed ... params: { allowedValues: [ 'app', 'modules' ] },
params: { propertyName: 'modelVersion' }
modelVersion 属于 oh-package.json5 和 hvigor-config.json5。
坑四:runtimeOS 不一致,模块和产品各说各话。 模块 entry/build-profile.json5 里写了 "runtimeOS": "OpenHarmony",产品是 HarmonyOS:
Error Message: The runtimeOS configuration of the target entry:default does not
match the product default. At file: .../entry/build-profile.json5
* Try the following: Change runtimeOS 'OpenHarmony' to 'HarmonyOS'
老模板(react-native-harmony-cli 时代)全是 OpenHarmony,新 SDK 必须统一成 HarmonyOS。
坑五:RN 侧三连——Metro 解析不到本地库、@babel/runtime 缺失、--platform harmony 不存在。 三个报错按时间顺序:
error Unable to resolve module react-native-ohos-live-view from .../App.tsx
error Unable to resolve module @babel/runtime/helpers/interopRequireDefault
from .../react-native-ohos-live-view/src/index.ts
error: Invalid platform "harmony" selected. Available platforms are: "ios", "android", "native".
第一坑:file:.. 依赖的库源码在 example 之外,metro 不监视工程外目录——watchFolders 加上库根目录解决。第二坑:babel 转译库 TS 时注入 @babel/runtime helper,库根自己得装一份(@babel/runtime 进库的 dependencies)。第三坑:RN CLI 不认识 harmony 平台(RNOH 的 CLI 插件没装),直接用 --platform android 打包,RNOH 运行时照样加载——bundle 是 JS 字节码,平台差异在运行时由 Platform.OS 表达。
坑六:RNOH 0.86 的 ArkTS API 改了一整代。 照旧文档写 example 壳工程,一口气撞出五个编译错:
'"@rnoh/react-native-openharmony"' has no exported member 'RNOHCorePackage'. Did you mean 'RNOHPackage'?
Type '{ createRNPackages: ...; enableNDKText: true; ... }' is not assignable to type 'RNInstanceConfig'.
Property 'context' does not exist on type 'Index'.
Non-abstract class 'EntryAbility' does not implement inherited abstract member 'getPagePath' from class 'RNAbility'.
In an '@Entry' decorated component, the 'build' method can have only one root node.
逐条对齐:RNOHCorePackage → RNOHPackage;enableNDKText/enableCustomFont 从 RNInstanceOptions 里删掉了;RNInstanceConfig 类型不再导出(内联对象字面量);RNAbility 新增抽象方法 getPagePath(),onWindowStageCreate 里的手动 loadContent 删掉;RNApp({...}) 要包在 Column() 里。
坑七:实况窗 API 与网上教程的偏差比想象中大。 ArkTS 侧初版按网上教程写的,编译期连环报错,每一条都是教程与 SDK 2996 行 d.ts 的出入:
Module '"@kit.ShareKit"' has no exported member 'utd'.
Property 'showShareSheet' does not exist on type 'ShareController'.
Argument of type 'number' is not assignable to parameter of type 'LiveView'.
Namespace 'liveViewManager' has no exported member 'Text'.
utd 在 @kit.ArkData(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT);分享面板接口是 controller.show(context, options);stopLiveView 收 LiveView 对象;富文本类型叫 RichText 不叫 Text。凡是有 3000 行 d.ts 的 Kit,一律以 d.ts 为准,教程只当索引。
坑八:TurboModule 注册,ArkTS 侧和 C++ 侧要各注册一次,两处都是新版 API。 修完上面编译关,运行时 JS 侧还是抛:
[Error: Exception in HostObject::get for prop 'LiveView':
Couldn't find Turbo Module on the ArkTs side, name: 'LiveView'
两个坑叠在一起。其一,RNOH 0.86 弃用了 0.72 时代教程满天飞的 createTurboModulesFactory 写法(继续写不报错、但永远查不到模块),必须改成按名字返回工厂:
export class LiveViewPackage extends RNPackage {
override getUITurboModuleFactoryByNameMap(): Map<string,
(ctx: UITurboModuleContext) => UITurboModule | null> {
return new Map<string, (ctx: UITurboModuleContext) => UITurboModule | null>()
.set(LiveViewModule.NAME, (ctx) => new LiveViewModule(ctx));
}
}
其二,ArkTS 侧注册好之后,日志里 TM created: LiveView 出现了,但报错还在——这次的建议语变成了 “Have you linked a package that provides this turbo module on the CPP side?”。C++ 侧还要有一份 ArkTSTurboModule 绑定(JSI 桥),在 PackageProvider.cpp 里加一个只有 createTurboModule 的 Package:
SharedTurboModule LiveViewTurboModuleFactoryDelegate::createTurboModule(
Context ctx, const std::string& name) const {
if (name == "LiveView") {
return std::make_shared<ArkTSTurboModule>(ctx, name);
}
return nullptr;
}
ArkTS 模块 = ArkTS 实现 + C++ 绑定,缺一边都过不了 TurboModuleRegistry.getEnforcing。
但这只是"注册"关,真机上还有"方法表"关:注册完模块,真机调用却抛 TypeError: undefined is not a function,堆栈指向 JS 调用行,看起来像 JS 导出丢了(我一度以为是 babel 剥注释/平台内联优化把代码干掉了,还清了 metro 真实缓存——缓存在 /var/folders/.../T/metro-cache,不在 /tmp——都没用)。真相:C++ 侧的 ArkTSTurboModule 基类不会自动注册方法,必须子类化并手写 methodMap_ 方法表,否则 JSI 暴露出来的每个方法都是 undefined:
class LiveViewTurboModule : public ArkTSTurboModule {
public:
LiveViewTurboModule(const ArkTSTurboModule::Context ctx, const std::string name)
: ArkTSTurboModule(ctx, name) {
methodMap_ = {
ARK_ASYNC_METHOD_METADATA(isLiveViewEnabled, 0),
ARK_ASYNC_METHOD_METADATA(startLiveView, 1),
ARK_ASYNC_METHOD_METADATA(updateLiveView, 1),
ARK_ASYNC_METHOD_METADATA(stopLiveView, 1),
ARK_ASYNC_METHOD_METADATA(shareLiveViewCard, 1),
ARK_METHOD_METADATA(addListener, 1),
ARK_METHOD_METADATA(removeListeners, 1),
};
}
};
实现是 RNOHCorePackage/TurboModules/AppStateTurboModule.cpp——官方核心模块个个都有这张表,只有教程不会告诉你。排查这类"方法 undefined"问题时,JS 侧探针(console.log(Object.keys(NativeModule)))只会告诉你 promise 对象存在,真正要查的是 C++ 构造函数里有没有 methodMap_。
7. 现在怎么用:从 三方库 到依赖
JS 侧接入(npm):
npm install react-native-ohos-live-view
鸿蒙侧接入(HAR): 把 harmony/build/default/outputs/default/react_native_ohos_live_view.har 放进工程 libs/,entry/oh-package.json5:
"dependencies": {
"@rnoh/react-native-openharmony": "^0.86.0",
"react-native-ohos-live-view": "file:./libs/react-native-ohos-live-view.har"
}
pages/Index.ets 注册(三行核心):
function createPackages(ctx: RNPackageContext): Array<RNPackage> {
return [new RNOHPackage(ctx), new LiveViewPackage(ctx)];
}
构建命令(按顺序):
# 1. JS bundle(RNOH 运行时兼容 android 平台产物)
npx react-native bundle --platform android --dev false \
--entry-file index.js \
--bundle-output harmony/entry/src/main/resources/rawfile/bundle.hap \
--assets-dest harmony/entry/src/main/resources/rawfile/
# 2. 编三方库 HAR(库工程根)
hvigorw assembleHar -p module=react_native_ohos_live_view@default
# 3. 编 example HAP
hvigorw assembleHap --mode module -p product=default -p buildMode=debug
# 4. 签名(模拟器链路)
java -jar hap-sign-tool.jar generate-app-cert ... # 生成证书链
java -jar hap-sign-tool.jar sign-profile ... # 签 profile(绑定 UDID)
java -jar hap-sign-tool.jar sign-app ... # 签 HAP
# 5. 安装运行
hdc install liveview-signed.hap
hdc shell aa start -a EntryAbility -b com.example.rnohliveview
总结:
本文是一篇面向RNOH生态的技术实战文章,完整实现基于TurboModule封装鸿蒙LiveViewKit的三方库
react-native-ohos-live-view,适配外卖配送、打车、体育比分三大典型业务场景,打通实况窗胶囊态、卡片态、锁屏沉浸态三形态。文章基于DevEco Studio 26.0、HarmonyOS 7.0 API26、RNOH 0.84.5开展开发与真机验证,配套可运行示例工程并开放仓库地址。
很多开发者会把实况窗等同于常驻通知,但LiveViewKit拥有一套独立的模型体系,stopLiveView要求传入完整LiveView对象而非仅ID,所有接口返回携带独立业务码的LiveViewResult,同时内置sequence、timer、生命周期控制等系统能力,远不是简单通知。项目核心目标就是把这套原生结构体转为RN可直接调用的JS对象,通过TurboModule完成双向通信,同时提供一套应用内模拟器,解决模拟器无华为账号、缺少实况窗权益,无法渲染真实胶囊、锁屏卡片的痛点,保证业务数据流在调试环境下也能完整跑通。
在效果与形态层面,实况窗由系统SystemUI负责渲染,应用只负责提交结构化数据,胶囊、卡片、锁屏卡片属于同一份数据的多端投影,一次更新同步刷新三处视图。真机上胶囊态是状态栏极简窄条,适合后台长任务状态展示;卡片态是核心交互载体,支持配置最多3个业务按钮,需要显式开启isServiceButtonsDisplayed才会展示;锁屏态依托ExtensionAbility实现免解锁沉浸卡片。库内的RN模拟器复刻了全部布局、字段与交互逻辑,还基于PanResponder实现了左滑手势,联动ShareKit唤起系统分享面板,这个手势是应用侧模拟实现,并非系统实况窗原生回调。
原理部分梳理了整套调用链路:isLiveViewEnabled用来前置探测实况窗能力开关,返回false的原因包含账号未登录、权限关闭、应用缺少AGC实况窗白名单权益;startLiveView提交首屏数据,updateLiveView采用全量替换机制,依靠sequence序号做版本排序,不支持增量更新;stopLiveView需要缓存启动时的原始LiveView对象传给系统校验;原生侧所有状态变更、错误信息通过emitDeviceEvent以事件流形式回传给RN层。同时场景event字段会决定系统选用哪一套模板,传值错误会导致展示退化,锁屏沉浸卡片还需要额外配置liveViewLockScreenAbilityName指向对应的扩展能力。
工程架构上做了解耦设计,分为TS跨端API层、ArkTS TurboModule原生封装层、Example示例层。TS层提供类型定义、useLiveView Hook、预置场景构造器,对外暴露极简API,开发者只需要探测能力、启动实况窗、监听事件即可接入;ArkTS层封装LiveViewKit和ShareKit,维护LiveView对象缓存Map,用来满足stop接口的入参要求;示例工程内置状态机,模拟外卖多阶段流转、打车倒计时、比分计时进球,还做了竞态保护,通过running状态隔离update和stop,避免并发异常。开发中也有多处细节需要留意,胶囊分为文本、计时、进度三种类型不能混用;布局模板是数值枚举,比分模板字段为hostScore/guestScore;timer.time单位是毫秒,倒计时逻辑由系统自动渲染。
更多推荐


所有评论(0)