鸿蒙 PC 下 React Native 窗口状态避坑:AppState 无法识别窗口最小化,基于 TurboModule 封装窗口生命周期
窗口隐藏、窗口最小化、前台激活、后台休眠——这四个状态在手机上几乎是同一件事,在鸿蒙 PC 上却是完全不同的四件事。这篇文章用一个跑在 HUAWEI MateBook Pro 真机上的 React Native 三方库,把「系统到底发了哪几路信号」「四路信号怎么收敛成一个相位」「RN 的 AppState 为什么看不见最小化」。
示例仓库:https://atomgit.com/dijun_520/react-native-ohos-window-lifecycle
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-RN/ohos_react_native/tree/0.84-main
CPF-RN 鸿蒙社区:https://atomgit.com/CPF-rn
0. 环境与实测设备
| 项目 | 版本 / 型号 |
|---|---|
| DevEco Studio | 26.0.0 (26.x) |
| HarmonyOS SDK / API | 26.0.0 / API 26 |
| React Native / RNOH | 0.84.1(@rnoh/react-native-openharmony 0.84.1,C-API 架构) |
| Node.js | v22.11+ |
| 实测设备 | HarmonyOS 7 PC(MateBook Pro) |
1. 「最小化就等于销毁」
我一开始对窗口生命周期的理解,完全是移动端带过来的:页面看不见了,就是 onPageHide;页面被回收,就是 aboutToDisappear;页面重建,就是重新 aboutToAppear。
于是我第一版压根没写原生模块,直接用 RN 自带的 AppState 接了一下,想的是「窗口最小化 → 应用进后台 → AppState 变 background,我在 background 里暂停轮询就行」。
真机上点了一下标题栏的最小化按钮,然后把应用晾了两分钟,再点回来。
AppState 从头到尾一次都没变。
不是变得慢,是压根没收到回调。我加了一行日志:
// 最小化前后的 JS 日志(AppState 对照组)
18:12:03 AppState=active
18:12:41 AppState=active <- 这一行是我最小化之后 38 秒打印的
18:13:09 AppState=active
应用明明已经从屏幕上消失了,AppState 还说 active。
这就是第一个反直觉的地方:AppState 回答的是「进程在不在前台」,不是「窗口在不在用户眼前」。在手机上这两件事基本等价(应用切后台,窗口一定不可见),在 PC 上它们被拆开了——鸿蒙 PC 允许一个应用窗口被最小化、被别的窗口完全盖住、被拖到另一个屏,而进程依然是前台进程。
后来翻文档才看清楚,window 这一层自己有一条完整的生命周期事件流,和「应用」这一层是两套东西:
// @ohos.window.d.ts(SDK API 26)
on(type: 'windowEvent', callback: Callback<WindowEventType>): void;
// WindowEventType: WINDOW_SHOWN=1, WINDOW_ACTIVE=2, WINDOW_INACTIVE=3,
// WINDOW_HIDDEN=4, WINDOW_DESTROYED=7
on(type: 'windowVisibilityChange', callback: Callback<boolean>): void;
on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void;
// WindowStatusType: UNDEFINED=0, FULL_SCREEN=1, MAXIMIZE=2, MINIMIZE=3,
// FLOATING=4, SPLIT_SCREEN=5
一共三路,外加进程前后台那一路,才是完整的输入。
所以这个题目的边界很清楚:把窗口级的三路信号(可见性、窗口状态、窗口舞台事件)和进程前后台信号合成一个相位,让 JS 侧第一次能区分「窗口看不见」和「应用被挂起」。
拆开之后是三件事:
- 用 TurboModule 把
window与ApplicationContext上的四类回调接住,转成 RN 的 DeviceEvent; - 在原生侧做一次相位合成与去重,别把「拖动窗口」产生的事件洪水灌进 JS 桥;
- 在 JS 侧给一个 Hook + 一个事件 API,并且保证组件卸载时把原生回调真的摘掉。
2. 效果展示

这里每一行都不是装饰:顶部「前台激活」对应原生侧算出来的 phase = active,它是 visibility=visible + stage=active + appState=foreground 三个条件同时成立的结果;窗口 id = 368 是 ArkUI 给这个窗口分配的 ID,也是 window.getWindowProperties().id 的返回值;2090 × 1394 vp 是窗口矩形,不是屏幕分辨率。注意 status 显示的是 floating——窗口没最大化时,它既不是 FULL_SCREEN 也不是 MAXIMIZE。
中间那块「四路原始信号」是我特意留的调试面板:visibility 来自 windowVisibilityChange,status 来自 windowStatusChange,stage 来自 windowEvent,appState 来自 applicationStateChange。

这是点了标题栏最小化按钮之后的样子——窗口整个从屏幕上消失了,只剩桌面。**此刻应用进程还活着,JS 堆还在,setInterval 还在跳,但你已经没有任何办法截到它的界面了。

用 aa start 把窗口拉回来,相位回到「前台激活」,reason=status(是 windowStatusChange 那一路把它叫醒的)。

这张日志值得逐行读,它是四路信号真实到达顺序的原始记录:
21:14:41 status phase=active visibility=visible status=floating stage=active appState=foreground <- 恢复完成
21:14:41 stage phase=hidden visibility=visible status=minimize stage=active appState=foreground
21:14:41 stage phase=hidden visibility=visible status=minimize stage=shown appState=foreground
21:14:41 visibility phase=hidden visibility=visible status=minimize stage=hidden appState=foreground <- visibility 已翻 true,status 还压在 minimize
21:14:41 appState phase=hidden visibility=hidden status=minimize stage=hidden appState=foreground <- 恢复前最后一条
21:14:06 appState phase=sleeping visibility=hidden status=minimize stage=hidden appState=background <- 系统把进程判成后台,phase 进入 sleeping
21:14:06 visibility phase=hidden visibility=hidden status=minimize stage=hidden appState=foreground
21:14:05 AppState RN 自带的 AppState 变成 background <- 对照组终于动了
21:14:05 status phase=hidden visibility=visible status=minimize stage=hidden appState=foreground
21:14:05 stage phase=hidden visibility=visible status=floating stage=hidden appState=foreground
21:14:05 stage phase=inactive visibility=visible status=floating stage=inactive appState=foreground
21:13:11 visibility phase=active visibility=visible status=floating stage=active appState=foreground <- 冷启动完成
能读出三个结论:
第一,最小化瞬间的信号洪水:21:14:05 一秒之内连着来了 stage(inactive) → stage(hidden) → status(minimize),三条来自两路不同的回调,顺序在两次实验里并不固定。
第二,AppState 的盲区是「滞后且不确定」,不是「永远不知道」。第一次实验它 38 秒没动;这一次它在最小化后约 1 秒跟到了 background。它唯一回答的是「进程此刻在不在前台」,什么时候由系统调度决定,应用侧完全无法预期。而窗口被另一个窗口完全盖住时它根本不会动。
第三,恢复的次序同样是乱序的:visibility 先翻回 visible,status 还压在 minimize,直到 status → floating 那一条到达,相位才真正回到 active。如果 JS 侧直接拿 visibility 当「恢复」的依据,会在中间这几十毫秒里做出错误动作。
3. 原理:一个「窗口状态」,系统其实发了四路信号
先给一张映射表,把四路信号、它们的来源、以及应用要回答的问题对齐。
| 信号 | 鸿蒙 API | 回调形态 | 应用要回答什么 |
|---|---|---|---|
| 可见性 | window.on('windowVisibilityChange') | boolean | 窗口还在不在合成器上 |
| 窗口状态 | window.on('windowStatusChange') | WindowStatusType | 是最大化、最小化、悬浮还是分屏 |
| 窗口舞台 | window.on('windowEvent') | WindowEventType | SHOWN / ACTIVE / INACTIVE / HIDDEN / DESTROYED |
| 进程前后台 | ApplicationContext.on('applicationStateChange') | onApplicationForeground / onApplicationBackground | 进程有没有被系统压到后台 |
窗口是显示单位,页面是路由单位。 这句话是整篇文章的支点。窗口被最小化,动的是「显示单位」;页面实例、路由栈、JS 堆,全都属于「路由单位」,一点没动。这也是为什么在 ArkUI 里最小化窗口不会触发 onPageHide,更不会触发 aboutToDisappear。
四路信号里,最容易误用的是第一路。windowVisibilityChange 报 false 的场景至少有三类:
- 窗口被最小化;
- 窗口被另一个全屏窗口完全盖住;
- 窗口正在被系统做转场动画。
这三类在信号层面不可区分,都是「不可见了」。想把它们分开,必须看 windowStatusType——只有最小化才会给出 MINIMIZE。这也是为什么我的相位判定里,「不可见」和「最小化」是并列条件,而不是二选一:
// 判定「隐藏」的两个入口,满足任一即是
visibility == 'hidden' || status == 'minimize' || stage == 'hidden'
第三路 windowEvent 才是真正的「生命周期」:WINDOW_SHOWN 代表窗口创建并显示,WINDOW_ACTIVE 代表拿到焦点,WINDOW_INACTIVE 代表失去焦点但还在屏幕上,WINDOW_HIDDEN 代表从屏幕上消失,WINDOW_DESTROYED 是终点。
这里有个真机现象值得单独说:最小化时 WINDOW_HIDDEN 和 WINDOW_ACTIVE 会成对出现。恢复窗口的那一瞬间,WINDOW_ACTIVE 先到,windowVisibilityChange(true) 后到,中间有几十毫秒窗口是「已经 active 但还不可见」的。
4. 工程怎么搭
4.1 目录
react-native-window-lifecycle/
├── package.json # npm 包 + harmony.autolinking 元数据 + codegenConfig
├── src/
│ ├── specs/NativeWindowLifecycle.ts # codegen 规范(TurboModule 接口)
│ ├── types.ts # 对外类型:字面量联合 + 字段归一化
│ ├── index.ts # 公共 API:on / onPhase / getState / 引用计数
│ └── hooks/useWindowLifecycle.ts # React Hook
├── harmony/
│ ├── har/react_native_window_lifecycle.har # 打好的 HAR(含 cpp 与 generated)
│ └── react_native_window_lifecycle/
│ └── src/main/
│ ├── ets/WindowLifecycleTurboModule.ets # 主力:四路信号 + 相位合成
│ ├── ets/WindowLifecyclePackage.ets # ArkTS 侧注册入口
│ ├── cpp/WindowLifecyclePackage.h/.cpp # C++ 侧注册入口
│ └── cpp/generated/… # codegen 产物(勿手改)
└── example/
├── App.tsx # 演示页:四态徽标 + 信号面板 + 存活证据
├── src/specs/… # codegen 输入(与库内 spec 同源)
└── harmony/ # 壳工程(签名、cpp、RNOHPackagesFactory)
这次整理最关键的变化,是把「能跑」变成「能复用」,三条边界钉死:
- 库不依赖页面:原生模块不持有任何 UI 组件引用,只依赖
uiAbilityContext。 - 原生模块独立:
WindowLifecycleTurboModule没有任何 import 指向 example,example 删掉库照样能打包。 - example 只走公共 API:演示页没有一处直接调
NativeModules,全部走src/index.ts。
4.2 最小接入
三步:探能力 → 拿快照 → 听变化。
// example/App.tsx(节选)
import WindowLifecycle, { useWindowLifecycle } from 'react-native-window-lifecycle';
export default function App() {
const { snapshot, phase, isHidden, isSleeping } = useWindowLifecycle();
useEffect(() => {
if (!WindowLifecycle.isSupported()) return; // 1. 探能力
return WindowLifecycle.on('phaseChange', s => { // 3. 听变化
console.log(s.phase, s.status);
});
}, []);
// 2. 快照由 Hook 内部 getState() 拉取,首帧就有值
return <Text>{phase}</Text>;
}
4.3 通道协议
原生 → JS 只有一条 DeviceEvent,名字 windowLifecycleChange,payload 是一个扁平对象:
{
"phase": "hidden",
"visibility": "hidden",
"status": "minimize",
"stage": "hidden",
"appState": "foreground",
"windowId": 368,
"rectWidth": 2090,
"rectHeight": 1394,
"rectLeft": 0,
"rectTop": 0,
"isVisible": false,
"isActive": false,
"isSleeping": false,
"reason": "status",
"timestamp": 1762930512043
}
4.4 两个容易忽略的窗口期
第一个窗口期在启动时:RNApp 已经挂载、JS 已经开始跑,但 onWindowStageCreate 可能还没走完,这时候 window.getLastWindow(context) 会抛 BusinessError。我的处理是把订阅整个包在 try/catch 里,并且把 subscribed 标志放到 catch 之后——订阅失败时保持未订阅状态,下一帧 getState() 会重试。
第二个窗口期在卸载时:off('windowEvent') 之后紧接着窗口就被销毁,windowEvent 的 WINDOW_DESTROYED 有可能在你 off 之后才派发。所以我在 __onDestroy__ 里先退订再清引用,不给回调留一个半死的 window 对象。
5. 把代码讲透
5.1 拿窗口:为什么不能用 RNAbility 的 windowStage
最直接的写法是继承 RNAbility,把 onWindowStageCreate(windowStage) 里的 windowStage 存下来,然后 windowStage.getMainWindow()。这个写法能跑,但三方库拿不到 windowStage——那是宿主 Ability 的东西,库不应该要求使用方改 EntryAbility.ets。
库能拿到的只有 uiAbilityContext,所以只能走这条路:
// WindowLifecycleTurboModule.ets - ensureSubscribed()
const win = await window.getLastWindow(this.ctx.uiAbilityContext);
this.mainWindow = win;
const props = win.getWindowProperties();
this.store.windowId = props.id;
this.store.rectWidth = props.windowRect.width;
// 初始状态用同步查询补齐,别等第一次事件才准
this.store.status = this.mapStatus(win.getWindowStatus());
this.store.visibility = this.store.status === 'minimize' ? 'hidden' : 'visible';
三个细节值得单独说:
第一,getLastWindow 拿到的是「应用最上层窗口」,不是「主窗口」。本库只处理单窗口场景,多窗口(比如应用自己开了悬浮窗)时这个 API 会返回最后创建的那个,需要在 on 回调里再用 window.getWindowProperties().id 过滤。
第二,初始状态必须同步查一次。getWindowStatus() 是 API 12 起的同步接口,能直接拿到 FULL_SCREEN / MAXIMIZE / MINIMIZE / FLOATING / SPLIT_SCREEN。不查的话,应用冷启动时 status 会是 undefined,直到用户第一次动窗口才第一次有值——UI 上会闪一下。
第三,getWindowProperties() 里的 windowRect 是 vp 不是 px。我在演示页上显示 2090 × 1394 vp(默认窗口大小拖过一次之后的值),和系统设置里看到的窗口尺寸对得上;换成 px 数字会翻两三倍,第一次看到会以为取错了。
5.2 相位合成:四路信号怎么收敛成一个状态
四路信号是异步、乱序、可能重复的。做 UI 的人不想要四个布尔,想要一个状态。所以原生侧做一次收敛:
// WindowLifecycleTurboModule.ets - computePhase()
private computePhase(): string {
if (this.store.appState === 'background') {
return 'sleeping';
}
const hidden =
this.store.visibility === 'hidden' ||
this.store.status === 'minimize' ||
this.store.stage === 'hidden';
if (hidden) {
return 'hidden';
}
if (this.store.stage === 'active') {
return 'active';
}
return 'inactive';
}
优先级是硬的:sleeping > hidden > active > inactive。
第一,sleeping 排最前,因为进程后台是唯一一种「JS 会被系统节流」的状态,业务必须最优先响应。
第二,hidden 的判据是「或」不是「与」。三个条件任意一个成立就算隐藏。反过来的写法(三个都成立才算)在真机上会漏事件:最小化时 windowEvent 有时不派发 WINDOW_HIDDEN,只派发 INACTIVE,这时候只有 status = minimize 这一路是对的。
第三,inactive 是兜底而不是独立状态。窗口可见、进程前台、但 stage 既不是 active 也不是 hidden(比如 shown)时,落到 inactive。这个状态在 PC 上出现得很频繁:点一下任务栏、拖动窗口、弹出一个系统对话框,都会让窗口短暂失焦。
反直觉的地方在这里:不要用 isVisible 判断「能不能继续渲染」。isVisible 是 visibility === 'visible' && status !== 'minimize',它在 inactive 时是 true——窗口看得见、只是没焦点。真正该停渲染的是 phase === 'hidden'。
5.3 去重:拖动窗口一次会喷十几个事件
windowRectChange 这类事件在拖动时会高频触发,windowStatusChange 在最大化/还原动画期间也会连发。如果不做去重,JS 桥会被灌满,而且 React 会疯狂重渲染。
// WindowLifecycleTurboModule.ets - publish() / computeSignature()
private computeSignature(): string {
return this.computePhase() + '|' + this.store.visibility + '|' + this.store.status + '|' +
this.store.stage + '|' + this.store.appState + '|' +
this.store.rectWidth + 'x' + this.store.rectHeight;
}
private publish(reason: string): void {
this.lastReason = reason;
const signature: string = this.computeSignature();
if (signature === this.lastSignature) {
return;
}
this.lastSignature = signature;
this.ctx.rnInstance.emitDeviceEvent(EVENT_NAME, this.buildPayload(reason));
}
第一,签名里必须包含 rectWidth × rectHeight。只比相位的话,用户拖动改变窗口大小(相位一直是 active)就完全不会通知 JS,而 PC 上「窗口尺寸变了」往往意味着要重排布局。
第二,去重放在原生侧而不是 JS 侧。JS 侧去重要先把事件跨桥传过来,开销已经付掉了;跨桥才是瓶颈。
第三,getState() 会主动清空签名(this.lastSignature = '')。因为 getState() 是「用户主动要一次当前值」,即使和上次一样也必须返回,不能因为去重返回空。
5.4 ArkTS 的接口不能用对象字面量实现
这条踩得最莫名其妙。applicationStateChange 的回调类型是 ApplicationStateChangeCallback,在 .d.ts 里长这样:
// @ohos.app.ability.ApplicationStateChangeCallback.d.ts
export default class ApplicationStateChangeCallback {
onApplicationForeground(): void;
onApplicationBackground(): void;
}
在 TypeScript 里,我本能地写对象字面量:
// 这段在 ArkTS 里编译不过
appContext.on('applicationStateChange', {
onApplicationForeground: () => this.handleAppState('foreground'),
onApplicationBackground: () => this.handleAppState('background'),
});
ArkTS 的规则是「对象字面量必须有明确的类/接口类型,且不能靠结构化类型去凑一个带方法签名的类型」。所以只能老老实实写一个类:
// WindowLifecycleTurboModule.ets - AppStateCallback
class AppStateCallback extends ApplicationStateChangeCallback {
private onForeground: () => void;
private onBackground: () => void;
constructor(onForeground: () => void, onBackground: () => void) {
super();
this.onForeground = onForeground;
this.onBackground = onBackground;
}
onApplicationForeground(): void {
this.onForeground();
}
onApplicationBackground(): void {
this.onBackground();
}
}
第一,必须 extends 而不是 implements。它在 d.ts 里是 class 而不是 interface,implements 会因为找不到构造签名报错。
第二,回调要自己转一层。类实例是原生侧持有的,this 指向类本身而不是 TurboModule,所以构造时把外部的箭头函数存进来,方法体里再调。
第三,off 的时候要传同一个实例。appContext.off('applicationStateChange', this.appStateCallback),传 undefined 会把它当「取消该事件的所有订阅」。
5.5 C++ 那层壳:为什么 TurboModule 必须双侧注册
这是整个工程里最容易被跳过、也最容易在真机上炸的一步。
RNOH 的 TurboModule 解析在 C++ 侧,TurboModuleFactory.cpp 里有一段判断:ArkTS 侧已经创建出模块实例、但 C++ 侧没有 delegate 认领这个名字时,直接抛:
Couldn't find Turbo Module on the ArkTs side, name: 'RNWindowLifecycle'
> Have you linked a package that provides this turbo module on the CPP side?
所以库必须提供一个 C++ Package,把名字映射到 codegen 生成的桥:
// WindowLifecyclePackage.h
#include "generated/react_native_window_lifecycle/RNOH/generated/turbo_modules/RNWindowLifecycle.h"
class RNWindowLifecyclePackage : public Package {
public:
RNWindowLifecyclePackage(Package::Context ctx) : Package(ctx) {}
std::unique_ptr<TurboModuleFactoryDelegate> createTurboModuleFactoryDelegate() override {
class FactoryDelegate : public TurboModuleFactoryDelegate {
public:
SharedTurboModule createTurboModule(Context ctx, const std::string &name) const override {
if (name == "RNWindowLifecycle") {
return std::make_shared<RNWindowLifecycle>(ctx, name);
}
return nullptr;
}
};
return std::make_unique<FactoryDelegate>();
}
};
第一,C++ 类名必须和 package.json 里 harmony.autolinking.cppPackageClassName 一字不差。autolinking 生成 autolinking.cmake 与 RNOHPackagesFactory.h 时是按这个字符串拼的,写错就是链接期找不到符号。
第二,RNWindowLifecycle 这个类是 codegen 产物,路径由包名决定:generated/react_native_window_lifecycle/RNOH/generated/turbo_modules/RNWindowLifecycle.h。
第三,C++ 这层的 createTurboModule 返回 nullptr 是正常路径,不是错误。
而 ArkTS 侧只需要重写一个方法:
// WindowLifecyclePackage.ets
export class RNWindowLifecyclePackage extends RNOHPackage {
getUITurboModuleFactoryByNameMap(): Map<string, (ctx: UITurboModuleContext) => UITurboModule> {
const map = new Map<string, (ctx: UITurboModuleContext) => UITurboModule>();
map.set(RNWindowLifecycleTurboModule.NAME,
(ctx: UITurboModuleContext) => new RNWindowLifecycleTurboModule(ctx));
return map;
}
}
6. 踩坑和经验
坑一:codegen 把同一个模块生成了两套 C++,链接期重复定义。
现象是打开 cpp/generated/ 看到两个目录:react_native_window_lifecycle/ 和 window_lifecycle_example/,两套 RNWindowLifecycle.cpp 内容一样。
• …\cpp\generated\react_native_window_lifecycle\RNOH\generated\turbo_modules\RNWindowLifecycle.cpp
• …\cpp\generated\window_lifecycle_example\RNOH\generated\turbo_modules\RNWindowLifecycle.cpp
info Generated 31 file(s)
一开始以为 codegen 有 bug。后来才反应过来:example/package.json 里我也写了一份 harmony.codegenConfig(因为 example 里有 src/specs),而库自己的 package.json 也有一份。codegen-harmony 会把工程自身 + node_modules 里所有带 codegenConfig 的包都扫一遍,于是同名模块被生成了两次,目录名按各自的包名命名。
修复是删掉 example 那份,只让库声明规范:
// example/package.json —— 不要有 harmony.codegenConfig
{ "name": "window-lifecycle-example", "dependencies": { "react-native-window-lifecycle": "file:.." } }
能被 codegen 生成两遍的东西,链接器一定会发现。 看到重复符号,先去数一遍 codegen 的输入。
坑二:--mode project … assembleHar 在 hvigor 6.26.8 上根本不存在。
照老教程写 npm run build:har:
hvigorw --mode project -p module=react_native_window_lifecycle@default assembleHar --no-daemon
报:
AdaptorError: 00306054 Specification Limit Violation
Error Message: Task [ 'assembleHar' ] was not found in the project harmony.
Invalid command to execute the build task, please verify the parameters in the command and try again.
新版本的 hvigor 把 project 模式和 module 模式的参数拆开了,HAR 是模块级产物,必须走 --mode module 并且显式给 product:
hvigorw --mode module \
-p module=react_native_window_lifecycle@default \
-p product=default \
assembleHar --no-daemon
报错说「task 不存在」时,先怀疑 mode,再怀疑 task 名。
坑三:ArkTS 编译 OOM,报的却是 V8 的错。
FATAL ERROR: Zone Allocation failed - process out of memory
FATAL ERROR: Zone Allocation failed - process out of memory
这句和 ArkTS 一点关系都没有,是 V8 堆分配失败。我这台机器 16G 内存,当时可用只有 0.9G——上几个工程留下的 jest worker、一个没退出的 bundle-harmony、两个 ohpm install 还挂着。
两件事一起做才解决:先清掉残留进程(可用内存回到 2.2G),再给 hvigor 放宽老生代上限:
// harmony/hvigor/hvigor-config.json5
{
"modelVersion": "5.0.0",
"nodeOptions": { "maxOldSpaceSize": 4096 }
}
看到 FATAL ERROR: … out of memory 先看可用内存,别急着怀疑代码。
坑四:arkts-no-any-unknown 不是「你写了 any」。
1 ERROR: 10605008 ArkTS Compiler Error
Error Message: Use explicit types instead of "any", "unknown" (arkts-no-any-unknown)
At File: …/WindowLifecycleTurboModule.ets:226:11
那一行是 const payload = this.buildPayload(reason);。我没写 any,但 buildPayload 返回 ESObject,推断出来就是动态类型,后面 payload['stage'] 这种取值直接把类型系统绕过去了。
修法不是加 as any(ArkTS 不给),而是干脆别走 ESObject 取值——签名字段全部从强类型的 store 里拼:
private computeSignature(): string {
return this.computePhase() + '|' + this.store.visibility + '|' + this.store.status + '|' +
this.store.stage + '|' + this.store.appState + '|' +
this.store.rectWidth + 'x' + this.store.rectHeight;
}
ArkTS 里 ESObject 能进不能出:它当返回值可以,拿来当中间变量做属性访问一定炸。
坑五:资源名对不上,报的是一行看不懂的 11211120。
Error Code: 11211120
Error: Resource Pack Error
Error Message: The resource reference '$string:ability_desc' is not defined.
At file: …/build/default/intermediates/process_profile/default/module.json
module.json5 里写的是 $string:ability_desc,我在 string.json 里手写成了 EntryAbility_desc。差一个前缀,资源编译器不认。
module.json5 里每一个 $string: / $color: / $media: 都要在 resources/base/element 里有同名条目,这条没有捷径。
坑六:本地库用软链安装,Metro 会从库源码目录找不到 react-native。
error Unable to resolve module react-native from …\react-native-window-lifecycle\src\index.ts:
react-native could not be found within the project.
npm i file:.. 装出来的是软链,Metro 跟着链走进库目录之后,再往上找 node_modules 就找不到 example 的那份了(库目录自己的上级是工作区根目录,没有 node_modules)。
修法是在 metro 配置里把 example 的 node_modules 追加进搜索路径,并把 babel 运行时显式指路:
// example/metro.config.js
resolver: {
unstable_enableSymlinks: true,
nodeModulesPaths: [
path.resolve(__dirname, 'node_modules'),
path.resolve(__dirname, '..', 'node_modules'),
],
extraNodeModules: {
'@babel/runtime': path.resolve(__dirname, 'node_modules/@babel/runtime'),
},
}
nodeModulesPaths 是「追加」不是「替换」,所以不用写 disableHierarchicalLookup。少了 unstable_enableSymlinks,Metro 连软链都不会跟。
坑七:bundle-harmony 找不到 hermesc。
error Couldn't find hermesc at …\node_modules\react-native\sdks\hermesc\win64-bin\hermesc.exe
RN 0.84 的 react-native 包里只留了 sdks/hermes-engine,预编译的 hermesc.exe 挪到了独立依赖 hermes-compiler 里。默认路径还是老的,所以要显式指定:
npx react-native bundle-harmony --js-engine hermes \
--hermesc-dir node_modules/hermes-compiler/hermesc --dev false
RN 0.8x 上凡是「找不到某个二进制」的报错,先去 node_modules 里 find 一遍再改配置。
坑八:HAR 只有 9.6 KB,我一度以为打空了。
ls -l 看到产物 9600 字节,第一反应是「cpp 没打进去」。实际上 HAR 是 gzip 过的 tar,解开后结构完整:
package/src/main/cpp/WindowLifecyclePackage.h
package/src/main/cpp/generated/react_native_window_lifecycle/RNOH/generated/turbo_modules/RNWindowLifecycle.cpp
package/src/main/ets/WindowLifecycleTurboModule.ets
package/src/main/module.json
而且 autolinking 生成的 autolinking.cmake 用的是 ${OH_MODULES_DIR}/react_native_window_lifecycle/src/main/cpp —— 也就是说 CMake 要的是 HAR 解包后的 cpp 源码,不是 .so。这意味着 build:har 必须排在 assembleHap 之前,改完 ArkTS 或 cpp 也得重新打 HAR,否则编进 HAP 的还是上一版。
HAR 里的 cpp 是源码参与宿主编译的,别指望它像 so 一样「改了不重编也没事」。
坑九:Windows 上 260 字符路径限制,会让 ninja 在链接前一步倒下。
CMake 配置全过,build.ninja 也生成了,卡在编译阶段:
> hvigor WARN: ninja: error: Stat(C:/Users/PC/WorkBuddy/2026-11-13-16-39-32/
react-native-window-lifecycle/example/harmony/oh_modules/@rnoh/react-native-openharmony/
src/main/cpp/patches/react_native_core/react/renderer/textlayoutmanager/platform/harmony/
react/renderer/textlayoutmanager/TextLayoutManager.cpp): Filename longer than 260 characters
注意这个路径的构成:工作区名 2026-11-13-16-39-32(20 个字符)+ 库名 react-native-window-lifecycle(29 个)+ oh_modules/.ohpm/<哈希目录> + RNOH 自己的深层目录。RNOH 的 cpp 目录本身就有一层 patches/react_native_core/react/renderer/...,叠起来必超。
ninja 用的是 Win32 的文件接口,不认长路径,也不能靠 LongPathsEnabled 注册表项救(那要进程 manifest 声明)。我第一反应是建一条目录联接省事:
mklink /J C:\wlc C:\Users\PC\WorkBuddy\2026-11-13-16-39-32\react-native-window-lifecycle
结果联接没用——hvigor 是 Node 程序,fs.realpath 会把 junction 解析回真实路径,CMake 里记下的还是那串长路径。最后老老实实把整个工程(连 node_modules)物理复制到 C:\wlc,在那里完成构建:
robocopy <工程目录> C:\wlc /E
cd C:\wlc\example\harmony && hvigorw --mode module -p product=default assembleHap --no-daemon
所有绝对路径变成 C:/wlc/...,长度立刻回到 200 以内,ninja 一次通过。
路径长度这种东西平时感觉不到,一旦超了,报错信息指向的却是某个毫不相干的 .cpp 文件。 工程目录尽量短,或者一开始就建在盘的根层;junction 能骗过大部分工具,骗不过 Node 的 realpath。
坑十:C++ Package 的文件名必须和 cppPackageClassName 一字不差。
autolinking 生成宿主侧的 RNOHPackagesFactory.h 时,会直接按类名 include:
#include "RNWindowLifecyclePackage.h"
std::make_shared<rnoh::RNWindowLifecyclePackage>(ctx)
我最初的文件叫 WindowLifecyclePackage.h(类名是 RNWindowLifecyclePackage),于是编译报 fatal error: 'RNWindowLifecyclePackage.h' file not found——而文件明明就在 -I 指向的目录里,ls 都能列出来。我先怀疑 junction,再怀疑缓存,绕了半天,其实就是文件名和生成器 expectations 对不上:autolinking 假定「头文件名 == cppPackageClassName.h」,不满足就直接说找不到。把两个文件重命名为 RNWindowLifecyclePackage.h/.cpp 立刻通过。
遇到「明明存在却说找不到」的头文件报错,先核对文件名是不是和注册类名完全一致,再查路径。
7. 现在怎么用:从 三方库 到依赖
7.1 接入
npm i react-native-window-lifecycle
库的 package.json 里有完整的 autolinking 元数据:
{
"harmony": {
"autolinking": {
"mainHarPath": "./harmony/har",
"ohPackageName": "react_native_window_lifecycle",
"etsPackageClassName": "RNWindowLifecyclePackage",
"cppPackageClassName": "RNWindowLifecyclePackage",
"cmakeLibraryTargetName": "react_native_window_lifecycle"
}
}
}
宿主工程只要保留 createRNOHModulePlugin({ codegen: null }),RNOHPackagesFactory.ets、RNOHPackagesFactory.h、autolinking.cmake 三个文件会自动生成,不需要手写注册。
7.2 构建命令
cd example
npm install
npm run codegen # 生成 C++ / ArkTS 胶水
npm run build:har # 打 HAR(含 cpp 源码)
cd harmony && ohpm install --all
cd .. && npm run bundle # 生成 rawfile/hermes_bundle.hbc
npm run build:hap
npm run install:hap
总结:
本文针对鸿蒙PC(MateBook Pro)上React Native开发的痛点:RN自带
AppState仅能感知进程前后台,无法识别窗口最小化、遮挡、失焦这类窗口级状态,而鸿蒙PC窗口和进程生命周期相互独立,最小化仅收起窗口,JS上下文、页面实例不会销毁。
基于RNOH 0.84 C-API架构,通过TurboModule封装,对接鸿蒙四路原生信号:窗口可见性、窗口状态、窗口舞台事件、应用进程状态,在原生层做信号收敛、去重,输出统一相位active/hidden/inactive/sleeping,并提供JS Hook与事件API,规避拖动窗口带来的事件洪水,同时处理订阅时机、回调解绑等时序问题。
实现上库不侵入宿主Ability,仅依赖uiAbilityContext,采用ArkTS+C++双侧TurboModule注册、Codegen自动胶水、HAR产物+autolinking自动注册,做到开箱复用。文中同步整理了整套开发踩坑清单,覆盖Codegen重复生成、hvigor构建参数、ArkTS类型限制、Metro软链解析、Windows长路径、Hermes编译、HAR构建特性、C++包注册等真机编译、打包、运行时问题,给出对应修复方案。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)