让 JS 感知会变形的鸿蒙窗口:RNOH 0.84 TurboModule 开发实录,封装窗口分屏能力,梳理 ArkTS 注册、事件防抖
RN 怎么在鸿蒙上"看见"窗口形态的变化、ArkTS 侧怎么把 @ohos.window 的能力封装成三方库、双 React 与 Metro 抢包这些工程坑怎么绕——这篇文章用一个跑在折叠电脑真机上的窗口分屏 Demo,把这三个问题一次讲透。从悬浮窗拖到全屏,状态徽标从"悬浮窗 2090×1394"变成"全屏 3120×2080",全程不用 JS 轮询一次。
示例仓库:https://atomgit.com/dijun_520/react-native-ohos-window-splitscreen
社区引导:框架源码与版本发布见 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. “窗口不就是调几个方法”
鸿蒙的窗口 API(@ohos.window)是公开能力,maximize、minimize、setWindowBrightness 这些方法名字都摆在文档里,封装成 RN 三方库不就是"JS 调一个 Promise,ArkTS 转发一次 API"的事。
第一版把 ArkTS 侧的方法全写完,真机一跑才发现我漏掉了这道题真正的主干:RN 组件树对窗口形态变化是瞎的。应用以自由窗口形态打开(折叠电脑上默认就是),我拖拽窗口边缘,React 界面纹丝不动——布局还是按启动时那一帧的尺寸渲染;我把窗口拖进分屏,界面既不知道自己变窄了,也不知道顶上多了一条状态栏。打开 hilog,ArkTS 侧的 windowStatusChange、windowSizeChange 在疯狂打印,而 JS 侧一片死寂。
11-14 02:25:40.566 2267 2267 I A0BEEF/com.rnoh.awesomeproject/#RNOH_CPP: RNInstanceCAPI::updateSurfaceConstraints
11-14 02:25:40.610 2267 2267 I A0BEEF/com.rnoh.awesomeproject/#RNOH_CPP: CustomNode: markDirty executed on main thread
RNOH 自己会处理 surface 尺寸(第一段日志),但"窗口现在是全屏还是分屏""设备当前允不允许悬浮窗"这类窗口级语义,RNOH 不会替你翻译成 React 状态。所以这个题目的边界很清楚:把 @ohos.window 的状态查询与三类窗口事件封装成 TurboModule,让窗口的每一次变形都变成 React 状态机的一次更新。
拆下来是三件事:
- 纯 ArkTS TurboModule 的完整三件套怎么写(ArkTS 类 + C++ methodMap + Package 注册,0.84 的注册方式和网上旧资料不一样);
windowSizeChange每帧一次的事件怎么节流转发才不会把 JS 刷爆;- RN 0.84 + React 19 的 bundle 在"库源码位于 example 之外"时怎么打包才不会踩出双 React。
2. 效果展示
应用启动后就是自由窗口形态(折叠电脑默认),Demo 首页长这样:

这里每一行都不是装饰:
- 状态徽标"悬浮窗 2090 × 1394 px" —— 一次
getSnapshot()的返回值:getWindowStatus()返回FLOATING,getWindowProperties().windowRect给出宽高; - windowId: 491 ——
props.id,这扇窗口在系统里的真实句柄号,后面点击"最大化"时窗口 ID 没变,变的只是形态; - 自由窗口:是 ——
isInFreeWindowMode(); - 全局模式位: 4 ——
window.getGlobalWindowMode()的位标志,4表示设备当前处于悬浮窗模式(1 全屏 / 2 分屏 / 4 悬浮 / 8 画中画,可叠加); - 全屏 ✗ | 分屏 ✗ | 悬浮 ✓ —— 把全局模式位拆成三个布尔,对应快照 JSON 里的
globalModeFullscreen/globalModeSplit/globalModeFloat。
然后用 uitest 在真机上点击"最大化"按钮(JS 侧调用 WindowSplitScreen.maximize(),ArkTS 侧转发 win.maximize()):

窗口铺满 3120×2080 的整块屏幕。这张截图里藏着一个值得单独讲的设计:状态徽标已经变成"全屏 3120 × 2080 px",而下面的快照卡片还显示着启动时探测到的"自由窗口: 是 / 悬浮 ✓"——这不是 bug,是两条数据通路的刻意的分工。徽标和尺寸来自 windowStatusChange / windowSizeChange 事件推送,事件一到 React 立即重绘;快照卡片则是 getSnapshot() 的一次性切片,要按"重新探测"才刷新。
拖拽窗口边缘缩放时,尺寸卡片会实时跟着变,但 JS 每秒最多收 6~7 次 sizeChanged 事件(150ms 节流),而不是每帧 120 次。
降级边界也交代一下:getGlobalWindowMode() 是 API 20+ 的接口,低版本设备上捕获异常后按 -1 处理,三个勾选显示为未知;setSupportedWindowModes 在手机形态上声明悬浮窗形态不会报错,但系统不一定真的允许拖成悬浮窗。
3. 原理:窗口事件到底走了哪几步
先把系统的模型摆清楚。在鸿蒙上,窗口是系统管理的资源,RN 组件树只是它表面的一层皮。窗口的创建、形态切换、尺寸变化全部由窗口管理器(WMS)裁决,应用拿到的是事件通知和一个受限的操作接口。RN 应用在鸿蒙上跑在 Ability 的窗口里,RNOH 把 React 渲染的 surface 贴在这个窗口上——所以"窗口变形"这条信息要到达 React,必须经过三层翻译:
WMS(窗口管理器)
│ windowStatusChange / windowSizeChange / freeWindowModeChange
▼
ArkTS 侧(WindowSplitScreenTurboModule) ← getWindowStatus / getGlobalWindowMode
│ emitDeviceEvent('windowSplitScreenEvent', payload)
▼
C++ 侧(ArkTSTurboModule + methodMap_) ← JSI 层暴露方法与事件通道
│ CallInvoker 调度到 JS 线程
▼
JS 侧(NativeEventEmitter + useWindowSplitScreen) ← setState 驱动 React 重渲染
本库用到的 @ohos.window 能力一张表列全:
| 能力 | API | 方向 | 说明 |
|---|---|---|---|
| 窗口状态 | win.getWindowStatus() | JS → ArkTS → JS | WindowStatusType 枚举,转字符串回传 |
| 自由窗口 | win.isInFreeWindowMode() | JS → ArkTS → JS | 2in1/平板可拖拽形态的判断 |
| 全局模式 | window.getGlobalWindowMode() | 同上 | API 20+,位标志可叠加,低版本降级 |
| 窗口属性 | win.getWindowProperties() | 同上 | 取 id 与 windowRect |
| 最大化/最小化 | win.maximize() / minimize() | JS → ArkTS | 2in1 与 PC 场景 |
| 沉浸式 | win.setWindowLayoutFullScreen() | JS → ArkTS | 退出时补 setWindowSystemBarEnable |
| 状态栏 | win.setWindowSystemBarProperties() | JS → ArkTS | 背景色 + 前景深浅 |
| 亮度/常亮/背景色 | setWindowBrightness 等一组 | JS → ArkTS | -1 恢复跟随系统 |
| 窗口形态声明 | win.setSupportedWindowModes() | JS → ArkTS | 分屏适配的前置声明 |
| 避让区 | win.getWindowAvoidArea() | JS → ArkTS → JS | 分屏/沉浸式布局适配 |
| 状态事件 | win.on('windowStatusChange') | ArkTS → JS | 全屏/最大化/分屏/悬浮切换 |
| 尺寸事件 | win.on('windowSizeChange') | ArkTS → JS | 高频,150ms 节流 + 尾帧补发 |
| 形态事件 | win.on('freeWindowModeChange') | ArkTS → JS | 自由窗口进出 |
两个细节决定了后面所有的降级逻辑:一是事件在 ArkTS 侧和窗口同生命周期,绑定一次就不再解绑(RN 实例销毁时 TurboModule 一起销毁,窗口监听随之失效,不需要手动 off 配对);二是所有方法的返回值统一收口成 Promise<string>,字符串内容是 {ok:true,...} 或 {ok:false,error} 形态的 JSON——这是为了让 C++ 侧的 methodMap_ 只需要声明 ARK_ASYNC_METHOD_METADATA 一种元数据,也让 JS 侧的解析逻辑可以写成一个函数。
4. 工程怎么搭
这次整理最关键的变化,是把"能跑"变成"能复用":库本体和 example 彻底分离,lib 不依赖任何页面,example 只走公共 API。仓库结构对齐 CPF-RN 组织的三方库范式:
react-native-ohos-window-splitscreen/
├── package.json # npm 包声明,peerDependencies 钉死 react/react-native 版本
├── src/ # JS/TS 侧(发布到 npm 的部分)
│ ├── NativeWindowSplitScreen.ts # TurboModule 规格声明(codegen 的依据)
│ ├── index.ts # 公共 API:isSupported/getSnapshot/.../on
│ └── hooks/
│ └── useWindowSplitScreen.ts # React 状态机 Hook
├── harmony/ # ArkTS 侧(以 HAR 形式被宿主消费)
│ └── window_split_screen/
│ ├── Index.ets # HAR 导出入口
│ ├── oh-package.json5 # HAR 包声明
│ └── src/main/ets/
│ ├── WindowSplitScreenTurboModule.ets # 核心实现(窗口 API + 事件桥)
│ └── WindowSplitScreenPackage.ets # 0.84 注册入口
└── example/ # 可独立构建的演示壳工程
├── src/App.tsx # 演示界面(状态徽标/快照/控制/事件日志)
├── metro.config.js # 关键:库外源码的依赖解析修复
└── harmony/ # RN 壳工程(entry + HAR 依赖)
├── entry/src/main/ets/
│ ├── RNPackagesFactory.ets # 宿主注册 WindowSplitScreenPackage
│ └── pages/Index.ets # RNApp 装载 + bundle Provider
└── entry/src/main/cpp/
└── PackageProvider.cpp # C++ 侧 methodMap_ 与 delegate
三条边界:lib 不 import example 的任何东西;ArkTS 实现独立成 HAR,宿主工程以 file 依赖消费;example 的所有功能只走 src/index.ts 暴露的公共 API,不直连 TurboModule spec。
最小接入只要三步,15 行以内:
// App.tsx —— 探能力 → 调用 → 听流
import WindowSplitScreen, { useWindowSplitScreen } from 'react-native-ohos-window-splitscreen';
function App() {
const { snapshot, status, eventLog, refresh } = useWindowSplitScreen();
if (!WindowSplitScreen.isSupported()) {
return <Text>非鸿蒙环境,能力不可用</Text>;
}
// snapshot: {windowId, status, inFreeWindowMode, globalModeRaw, width, height}
// status: 'FULL_SCREEN' | 'MAXIMIZE' | 'MINIMIZE' | 'FLOATING' | 'SPLIT_SCREEN'
return <Button title="最大化" onPress={() => WindowSplitScreen.maximize()} />;
}
通道协议是纯 ArkTS TurboModule 标准形态:JS 调用经 JSI 进入 C++ ArkTSTurboModule,按 methodMap_ 的元数据转到 ArkTS 侧实例的同名方法,Promise<string> 原路解析回 JS。事件走 emitDeviceEvent,一条通道三种事件,用 kind 字段区分。JS 侧收到的事件长这样:
{"kind":"statusChanged","status":"FLOATING"}
{"kind":"sizeChanged","width":2090,"height":1394}
{"kind":"freeWindowModeChanged","inFreeWindowMode":true}
有两个容易被忽略的窗口期。一是 TurboModule 上下文就绪之前不能碰任何原生对象:NativeEventEmitter 不能在模块顶层 new(第 6 节坑 6 会展开)。二是 首次 getSnapshot() 兼任了事件绑定的触发器:getMainWindow() 第一次被调用时才取窗口并 on 三类事件,如果业务只订阅事件从不调用任何方法,事件绑定就不会发生——所以 useWindowSplitScreen 的 useEffect 里先 refresh() 再订阅,保证两条路径都触发过 getMainWindow()。
5. 把代码讲透
5.1 纯 ArkTS TurboModule:0.84 的注册方式变了
场景句先放在这:网上能搜到的 RNOH 三方库资料大多停留在 0.72 时代,照抄 createTurboModulesFactory 会得到一个"永远不会被调用"的工厂。0.84 上注册纯 ArkTS TurboModule 的正确姿势是重写 getUITurboModuleFactoryByNameMap:
// WindowSplitScreenPackage.ets —— 0.84 注册入口
export class WindowSplitScreenPackage extends RNPackage {
getUITurboModuleFactoryByNameMap(): Map<string, (ctx: UITurboModuleContext) => UITurboModule> {
const map = new Map<string, (ctx: UITurboModuleContext) => UITurboModule>();
map.set('WindowSplitScreen', (ctx: UITurboModuleContext): UITurboModule => {
return new WindowSplitScreenTurboModule(ctx);
});
return map;
}
}
三个细节值得单独说。第一,模块类要继承 UITurboModule 而不是 TurboModule:只有 UITurboModule 的 context 里才有 uiAbilityContext,窗口 API 全都需要它(window.getLastWindow(this.ctx.uiAbilityContext))。第二,map 的 key 必须与 JS spec 的模块名、C++ delegate 的判断名三处一字不差,本库三处都是 'WindowSplitScreen',错一处就是运行时 “Couldn’t find Turbo Module”。第三,工厂 map 返回的是创建函数而不是实例,RNOH 会在需要时(含实例清理重建)多次调用它。
5.2 C++ 侧的 methodMap_:缺一行,JS 侧就少一个方法
纯 ArkTS TurboModule 的另一半在 C++。JSI 层不认识 ArkTS 对象,RNOH 用 ArkTSTurboModule 包装,而包装器只暴露 methodMap_ 里声明过的方法:
// example/harmony/entry/src/main/cpp/PackageProvider.cpp
class WindowSplitScreenArkTSTurboModule : public ArkTSTurboModule {
public:
WindowSplitScreenArkTSTurboModule(const ArkTSTurboModule::Context ctx, const std::string name)
: ArkTSTurboModule(ctx, name) {
methodMap_ = {
ARK_ASYNC_METHOD_METADATA(getSnapshot, 0),
ARK_ASYNC_METHOD_METADATA(maximize, 0),
ARK_ASYNC_METHOD_METADATA(setStatusBarStyle, 2),
// ... 共 13 个方法,ARK_ASYNC_METHOD_METADATA(名称, 参数个数)
};
}
};
class WindowSplitScreenTurboModuleFactoryDelegate : public TurboModuleFactoryDelegate {
public:
SharedTurboModule createTurboModule(Context ctx, const std::string& name) const override {
if (name == "WindowSplitScreen") {
return std::make_shared<WindowSplitScreenArkTSTurboModule>(ctx, name);
}
return nullptr;
}
};
三个细节值得单独说。第一,参数个数是元数据的一部分:setStatusBarStyle(color, lightContent) 声明为 2,JS 传参个数不匹配会直接 undefined。第二,有 Promise 返回值的方法一律 ARK_ASYNC_METHOD_METADATA,本库所有方法都是这个形态,这也是"返回值统一收口成 JSON 字符串"的红利。第三,宿主工程的 RNPackagesFactory.ets(ArkTS 侧)和 PackageProvider.cpp(C++ 侧)都要注册,两边只注册一边的现象都是"模块对象存在但方法全是 undefined"。
5.3 事件节流:150ms 间隔 + 尾帧补发
windowSizeChange 在拖拽缩放时每帧触发一次,高刷屏上就是 120Hz 的调用频率。每个事件都 emitDeviceEvent 一次,JS 线程会被 setState 刷到卡顿:
// WindowSplitScreenTurboModule.ets - throttledSizeEmit()
private throttledSizeEmit(size: window.Size): void {
const now = new Date().getTime();
const elapsed = now - this.lastSizeEmitTime;
if (elapsed >= 150) {
this.lastSizeEmitTime = now;
this.emitSize(size); // 距上次发送够 150ms:直接发
return;
}
this.pendingSize = size; // 间隔内的帧先记下来
if (this.trailingTimer === -1) {
const wait = 150 - elapsed;
this.trailingTimer = setTimeout(() => { // 尾定时器补发最后一帧
this.trailingTimer = -1;
if (this.pendingSize !== null) {
this.lastSizeEmitTime = new Date().getTime();
this.emitSize(this.pendingSize);
this.pendingSize = null;
}
}, wait);
}
}
三个细节值得单独说。第一,必须有尾帧补发:只做间隔丢弃的话,拖拽结束后的最后一帧会被丢掉,JS 侧定格在倒数第二帧的尺寸——布局永远差一截。第二,windowStatusChange 不节流:状态切换本身就是低频事件,而且它是语义信号不是连续量,丢帧的代价是丢状态。第三,节流状态放在 TurboModule 实例字段里而不是闭包里:RN 实例清理重建时实例一起重建,节流窗口自动归零,不需要手工复位。
5.4 快照协议:一张 JSON 拿全六个问题
布局适配要问的问题无非六个:现在什么状态、是不是自由窗口、设备全局允不允许、窗口多大、我的 ID 是谁。getSnapshot() 一次全给:
// WindowSplitScreenTurboModule.ets - getSnapshot()(节选)
const win = await this.getMainWindow();
const status = win.getWindowStatus();
const inFree = win.isInFreeWindowMode();
const props = win.getWindowProperties();
let globalModeRaw = -1;
try {
globalModeRaw = await window.getGlobalWindowMode(); // API 20+
} catch (e) {
// 不支持的设备保持 -1,JS 侧按未知处理
}
return `{"ok":true,"windowId":${props.id},` +
`"status":"${statusToString(status)}","inFreeWindowMode":${inFree},` +
`"globalModeRaw":${globalModeRaw},...` +
`"width":${props.windowRect.width},"height":${props.windowRect.height}}`;
这里有一个反直觉陷阱:getGlobalWindowMode() 是静态方法,挂在 window 命名空间上而不是窗口实例上,我最初写成 win.getGlobalWindowMode() 直接编译不过;它又是 API 20+ 的接口,低版本上调用会抛错——所以包一层 try/catch,失败时回 -1,JS 侧三个布尔全部按未知显示。另一个细节是避让区的序列化:AvoidArea 不是矩形,它是 visible 加上下左右四个矩形,每块取"厚度"(上下取 height、左右取 width)才够布局用:
// WindowSplitScreenTurboModule.ets - avoidAreaToJson()
function avoidAreaToJson(a: window.AvoidArea): string {
return `{"visible":${a.visible},"top":${a.topRect.height},"bottom":${a.bottomRect.height},` +
`"left":${a.leftRect.width},"right":${a.rightRect.width}}`;
}
5.5 JS 状态机 Hook:把事件流变成 React 状态
最后一块拼图在 JS 侧。useWindowSplitScreen 挂载时探测一次快照,然后订阅三类事件自动维护状态:
// src/hooks/useWindowSplitScreen.ts(节选)
const [snapshot, setSnapshot] = useState<WindowSnapshot | null>(null);
const mounted = useRef(true);
const refresh = useCallback(async () => {
if (!WindowSplitScreen.isSupported()) { setLoading(false); return; }
const snap = await WindowSplitScreen.getSnapshot();
if (!mounted.current) return;
setSnapshot(snap);
}, []);
useEffect(() => {
mounted.current = true;
refresh(); // 先探测:兼任事件绑定的触发器
const offStatus = WindowSplitScreen.on('statusChanged', payload => {
if (!mounted.current) return;
pushLog(`状态变化 -> ${payload.status}`);
setSnapshot(prev => (prev ? { ...prev, status: payload.status } : prev));
});
const offSize = WindowSplitScreen.on('sizeChanged', payload => {
if (!mounted.current) return;
setSize({ width: payload.width, height: payload.height });
});
return () => { mounted.current = false; offStatus(); offSize(); offFree(); };
}, [refresh, pushLog]);
三个细节值得单独说。第一,isSupported() 用 Platform.OS === 'harmony' 判断——上游 @types 没收录 'harmony' 字面量,要 as string 一下;非鸿蒙平台 Hook 返回安全空态,组件不会崩。第二,卸载后的异步回调全部用 mounted.current 挡住:getSnapshot() 是异步的,快速进出页面的场景里 Promise 回来时组件已经卸载,直接 setState 会警告。第三,事件订阅的取消函数在 cleanup 里逐一调用,on() 返回的是 sub.remove() 的包装,谁订阅谁取消。
6. 踩坑与经验
坑 1:ArkTS 编译缓存里出现一个叫 D: 的目录。 现象是 default@CompileArkTS 必挂,全量清缓存重建也挂:
00306062 Specification Limit Violation
Error Message: EINVAL: invalid argument, mkdir
'D:\RN\WindowSplitDemo\harmony\entry\build\default\cache\default\default@CompileArkTS\esmodule\debug\D:'
一开始以为是 hvigor 缓存损坏,删了 .hvigor、entry/build、.cxx 全量重建,报错一字不差。后来才反应过来:错误信息里那个 debug\D: 是编译器把某个源文件的绝对路径按目录层级展开时,把盘符 D: 当成了第一级子目录名。用 PowerShell 递归枚举工程里的 ReparsePoint,果然顶层 oh_modules 是一个指向另一个工程(D:\RN\FilePermDemo)的 junction——依赖链路里任何一段指向工程外,编译器就会在缓存里拼出非法路径。
坑 2:ohpm 子模块的 lock 文件残留旧工程路径。 换了工程目录后构建报资源编译错误,错误信息里居然是旧工程的绝对路径。排查发现子模块的 oh-package-lock.json5 里锁着旧的 file 依赖路径。删掉所有子模块 lock、.hvigor、build 目录重建后消失。lock 文件是可再生的,搬家/拷工程时果断删。
坑 3:应用一启动就报应用名未注册。 LogBox 直接甩脸:
'WindowSplitScreenDemo' has not been registered. This can happen if:
* Metro (the local dev server) is running from the wrong folder...
* A module failed to load due to an error and AppRegistry.registerComponent wasn't called.
我盯着自己的 AppRegistry.registerComponent('WindowSplitScreenDemo', ...) 看了半天没毛病。后来发现本机 8081 端口残留着一个上一个项目启动的 Metro——壳工程的 AnyJSBundleProvider 里 MetroJSBundleProvider 排在最前,设备优先从 Metro 拉包,拉到的是别人项目的 bundle。杀掉 Metro 进程立刻恢复。
坑 4:加载到了一个不存在的 App。 又一次启动后报:
Error: Exception in HostObject::get for prop 'WindowTitlebar'.
Couldn't find Turbo Module on the ArkTS side, name: 'WindowTitlebar'.
instanceName=WindowTitlebarExample
WindowTitlebar?我的工程里根本没有这个模块。排查链路:FileJSBundleProvider 指向应用沙箱 files/bundle.harmony.js,优先级高于资源 bundle——沙箱里躺着上一个实验推上去的旧包(窗口标题栏 Demo,恰好和我用同一个签名 bundleName)。卸载重装清掉沙箱后恢复。更坑的是后来又复发了一次:另一台开发会话往设备推了同 bundleName 的包,install -r 把我的覆盖了。
坑 5:Cannot read property 'useState' of null。 应用能启动、LogBox 能弹,一渲染主组件就崩:
Render error: Cannot read property 'useState' of null
Component Stack: App -> ViewWithRef -> ...
这是双 React 的典型症状:bundle 里打包了两份 react,组件用 A 份的 hooks,渲染器用 B 份的 reconciler,dispatcher 永远是 null。解包分析发现 example 用 file:.. 引库时,npm 在 example/node_modules/react-native-ohos-window-splitscreen/node_modules/ 下又装了一份嵌套依赖(含 react),库代码从嵌套副本里解析到了第二份 react。local file 依赖 + 库自带 node_modules 是双 React 的标准配方,打包前先 grep -c 'version="19' 确认 bundle 里 react 只有一份。
坑 6:[runtime not ready] 崩在模块求值阶段。 修完坑 5 后报错变成:
[runtime not ready]: TypeError: Cannot read property 'OS' of undefined
at anonymous (bundle.harmony.js:480:285)
runtime not ready 说明崩在模块初始化。罪魁是我图省事在 src/index.ts 顶层写了一句 const emitter = new NativeEventEmitter(NativeWindowSplitScreen)——模块求值早于 TurboModule 上下文就绪,NativeEventEmitter 构造内部访问 Platform 直接炸。改成惰性单例,首次调用时再创建:
let emitter: NativeEventEmitter | null = null;
function getEmitter(): NativeEventEmitter {
if (!emitter) {
emitter = new NativeEventEmitter(NativeWindowSplitScreen as never);
}
return emitter;
}
模块顶层只放声明,不放任何会触碰原生上下文的初始化。 这一行顺便修好了非鸿蒙平台的导入安全性。
坑 7:库源码解析到了原版 react-native。 修完坑 6 后在渲染期又见到 Cannot read property 'OS' of undefined,这次定位到 Platform 是 undefined。用 dev 模式 bundle(带模块路径)分析:全 bundle 408 个 react-native 模块都来自鸿蒙化包,唯独库源码的 react-native 导入解析到了原版 npm 包——而原版包的 Libraries/Utilities/Platform.js 在 harmony 平台上解析平台扩展失败,打出的模块自引用自己(},566,[1,566]),default 永远是 undefined。根因是库源码位于 example 目录之外,metro 向上找不到 example/node_modules,RNOH 的"react-native → 鸿蒙化包"重定向也随之失败。在 metro.config.js 的自定义 resolveRequest 里,对 example 外的源文件把 nodeModulesPaths 固定到 example 的 node_modules:
// example/metro.config.js(节选)
resolveRequest: (context, moduleName, platform) => {
if (moduleName === 'react-native-ohos-window-splitscreen') {
return { type: 'sourceFile', filePath: path.resolve(__dirname, '..', 'src', 'index.ts') };
}
const origin = context.originModulePath || '';
const outsideExample = !origin.startsWith(path.resolve(__dirname));
const ctx = outsideExample
? {...context, nodeModulesPaths: [path.resolve(__dirname, 'node_modules')]}
: context;
if (rnohResolveRequest) {
return rnohResolveRequest(ctx, moduleName, platform); // 保留 RNOH 的鸿蒙化重定向
}
return context.resolveRequest(ctx, moduleName, platform);
},
三方库的源码如果不在 example 目录树内,metro 的依赖解析根必须显式指定,否则 RNOH 重定向会静默失效。 修完后 dev bundle 里原版 react-native 模块数为 0,全部 408 个模块来自鸿蒙化包。
坑 8:ArkTS 严格模式下的三个编译错。 最后是一组 ArkTS 的类型洁癖:AvoidArea 不能当 Rect 用(它有 visible 加四个矩形),函数签名要写成 avoidAreaToJson(a: window.AvoidArea);SystemBarProperties 是接口不能用 new,要写类型化对象字面量 const props: window.SystemBarProperties = {...};取窗口 ID 用 props.id 而不是旧版的 WindowProperties.windowId。
7. 现在怎么用:从 三方库 到依赖
宿主工程三步接入。ArkTS 侧把本库目录拷进工程(或 ohpm file 依赖),在 oh-package.json5 声明:
// entry/oh-package.json5
"dependencies": {
"@rnoh/react-native-openharmony": "0.84.1",
"window_split_screen": "file:../window_split_screen"
}
JS 侧(发布后走 npm,现阶段可 file:../react-native-ohos-window-splitscreen):
npm install react-native-ohos-window-splitscreen
然后两处注册:RNPackagesFactory.ets 的 createRNPackages() 里 new WindowSplitScreenPackage(ctx),PackageProvider.cpp 里按 5.2 节写 delegate。构建走标准链路:
# JS bundle(务必 --platform harmony)
npx react-native bundle --platform harmony --dev false \
--entry-file index.js \
--bundle-output harmony/entry/src/main/resources/rawfile/bundle.harmony.js
# HAP(DevEco 内置 hvigor)
hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
# 真机
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.rnoh.awesomeproject
总结:
这篇文章围绕 RNOH 0.84(C-API 新架构) 下鸿蒙自由窗口与分屏能力的三方库开发完整落地展开,核心解决原生 RN 无法感知鸿蒙窗口形态变化的痛点。RNOH 本身只会同步 Surface 渲染尺寸,不会把系统窗口管理器 WMS 的窗口状态、悬浮/分屏/全屏语义、窗口句柄、全局模式位这类上层信息推送给 JS,直接调用
@ohos.window只是单向调用,做不到拖拽缩放、分屏切换时界面自动响应,这也是本次 TurboModule 封装的出发点。
整套方案采用纯 ArkTS TurboModule 范式,对齐 CPF-RN 社区三方库规范,分为 ArkTS 层、C++ 桥接层、JS/TS 层三段链路。ArkTS 侧订阅 windowStatusChange、windowSizeChange、freeWindowModeChange 三类系统事件,针对高频的尺寸变更实现 150ms 节流加尾帧补发,避免高刷屏下事件风暴打垮 JS 线程;低频状态事件不做节流,保证窗口语义切换不丢失。C++ 侧依靠 methodMap_ 声明异步方法元数据,统一通过 JSI 转发调用,所有接口返回标准化 JSON 字符串,降低两侧协议维护成本;同时适配 0.84 新版注册逻辑,依靠 getUITurboModuleFactoryByNameMap 注册 UITurboModule,区别于旧版 0.72 的工厂写法,规避模块注册失效的问题。JS 侧封装 useWindowSplitScreen Hook,对外提供快照查询、事件订阅、窗口控制能力,内部做惰性初始化,等到 TurboModule 上下文就绪后再创建 NativeEventEmitter,并通过 ref 标记组件挂载状态,防止异步回调在组件卸载后触发 setState 警告。
工程结构上严格分离库本体与 example 演示壳工程,库不依赖业务页面,Demo 只调用对外暴露的公共 API,方便其他项目直接作为 file 依赖引入,后续也可以发布到 npm。接入上只需要依赖 HAR、在 ArkTS 和 C++ 两处注册包、引入 Hook 即可,API 简洁,一行代码就能获取窗口快照、控制最大化最小化,同时内置降级逻辑:getGlobalWindowMode 这类高版本接口捕获异常后返回 -1,低版本设备兼容不崩溃;setSupportedWindowModes 仅做能力声明,不会硬编码强制开启悬浮窗,尊重不同设备形态的系统限制。
文章用很大篇幅记录真机调试中遇到的典型工程坑,也是 RNOH 新架构开发里很容易踩的共性问题:符号链接/ junction 导致 ArkTS 编译缓存拼出非法盘符路径、ohpm lock 文件残留旧绝对路径、多实例 Metro 抢包、同 bundleName 旧包残留在沙箱覆盖新代码、file 本地依赖引发双 React 副本导致 Hooks 失效、库源码在 example 外部时 Metro 解析跑偏加载原版 react-native、ArkTS 接口类型误用等。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐


所有评论(0)