窗口隐藏、窗口最小化、前台激活、后台休眠——这四个状态在手机上几乎是同一件事,在鸿蒙 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 Studio26.0.0 (26.x)
HarmonyOS SDK / API26.0.0 / API 26
React Native / RNOH0.84.1(@rnoh/react-native-openharmony 0.84.1,C-API 架构)
Node.jsv22.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. 效果展示

窗口激活状态:相位为 active,四路信号全部可见

这里每一行都不是装饰:顶部「前台激活」对应原生侧算出来的 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 还在跳,但你已经没有任何办法截到它的界面了。

恢复窗口:相位回到 active,挂载时间从 18s 连续走到 96s

用 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')WindowEventTypeSHOWN / 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++包注册等真机编译、打包、运行时问题,给出对应修复方案。

Logo

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

更多推荐