RNOH 的 TurboModule 怎么注册、窗口标题栏的窗口级 API 怎么桥给 JS、自定义沉浸式标题栏的"拖拽归系统、点击归组件"怎么落地,自由窗口里的 RN 三方库 react-native-ohos-window-titlebar,中间还夹着本次开发最值钱的一个坑:真机上 undefined is not a function,报错在 JS,根因却在 C++。

示例仓库:https://atomgit.com/dijun_520/react-native-ohos-window-titlebar

社区引导:框架源码与版本发布见 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. “标题栏不就是一行 API 吗”

窗口标题栏嘛,系统肯定给了 setWindowTitle("xxx") 这样的 API,RN 库要做的只是拿 TurboModule 包一层,暴露个 <WindowTitlebar /> 组件完事。桌面端的 Electron、WPF 都是这个思路。

结果第一个 demo 就被推翻了。我在 2in1 真机上把应用装起来,想改窗口标题栏的文字、想控制右上角三键的显隐,翻遍 @kit.ArkUI 的 window 模块才发现:标题栏(window decor)根本不是应用绘制的内容,它是窗口管理器的装饰。应用能做的只有几件事——让它显示/隐藏、改它的高度、控制三键的显隐和样式,仅此而已。想要完全自定义的标题栏?官方路径是把它整个藏掉,然后用普通 View 在页面顶部补一个"假的",再自己把窗口拖拽、最小化、最大化、关闭这些行为接回系统 API。

更大的坑在桥接层,按 RNOH 三方库的标准写法注册了 ArkTS 侧的 TurboModule,红屏:

Couldn't find Turbo Module on the ArkTS side, name: 'WindowTitlebar'.
The Turbo Module wasn't found on the CPP side either.

ArkTS 侧明明注册了,C++ 侧却不认识这个名字——RNOH 的 TurboModule 要两侧同时注册,而 codegen 在这个工程里又没跑起来。

所以这个题目的边界很清楚:这个库要做的不是"画一个标题栏",而是把鸿蒙窗口对象上散落的十几个窗口级 API,完整、类型安全地桥给 JS,再用纯 JS 组件把"自定义标题栏 + 拖拽区 + 三键"拼回一个开箱即用的体验。

拆开是三件事:

  • 原生标题栏控制:显隐、高度、三键显隐与样式、三键区位置读取;
  • 自定义沉浸式标题栏:藏掉原生栏,用 WindowTitlebarView 组件补位,拖拽区调 startMoving,三键调窗口控制 API;
  • 窗口事件:窗口状态变化、三键区位置变化、自由窗口模式变化,回传 JS。

2. 效果展示

应用启动后的默认界面:系统原生标题栏 WindowTitlebarDemo 与四块功能分区

这是应用启动后的默认形态。窗口最顶上是系统原生标题栏(应用名 WindowTitlebarDemo + 右侧三键),下面全是 RN 渲染的内容。这里每一行状态都不是装饰:

  • 日志区第一行 [init] 自由窗口能力支持: true——这是 App 启动时调 WindowTitlebar.isSupported() 的返回值,底层是 ArkTS 侧 canIUse('SystemCapability.Window.SessionManager')。它为 true 说明这台 2in1 设备支持自由窗口,整套 API 才有意义;
  • "原生标题栏"分区的六个按钮分别对应 setNativeTitlebarVisible / setNativeTitlebarHeight / setTitleButtonVisible / setDecorButtonStyle;
  • "窗口拖拽与控制"分区里那块浅蓝色区域是 WindowDragRegion,右侧四个小按钮对应 minimize / maximize / recover / close。

点击"启用自定义标题栏"后:原生标题栏被隐藏,蓝色自定义标题栏顶上

点击"启用自定义标题栏"之后的变化值得逐项看:系统原生标题栏整个消失了(setWindowDecorVisible(false) 生效),页面顶上出现蓝色自定义栏——左侧"RN 窗口标题栏 Demo"是标题文本,右侧"沉浸模式"是通过 actions 属性塞进去的自定义内容,最右边是最小化、最大化、关闭三键。这条蓝色栏百分百是 RN View 画出来的,和窗口管理器没有任何关系。日志区 [ok] 启用自定义沉浸式标题栏 说明这组调用(隐藏原生栏 + 渲染自定义栏)全部成功。

还原原生标题栏并读取三键区位置:日志里出现真实的 rect 数据

再点"还原原生标题栏",系统栏回来了。接着点"三键样式",先设置样式再读取三键区位置,日志里出现:

[ok] 设置三键样式
[rect] 三键区 {"right":0,"top":0,"width":140,"height":47}

这行 JSON 是 getTitleButtonRect() 的真实回传——width 140、height 47,就是右上角三键那块区域在窗口里的实际尺寸。做自定义标题栏避让时,JS 侧要的就是这个数。注意它的字段是 right/top/width/height,没有 left。

点击演示区的最小化按钮后:窗口从桌面消失,最小化到任务栏

最后这张是点击"最小化"按钮后的桌面——应用窗口不见了,缩进了任务栏。这是 WindowTitlebar.minimize() 一路穿透 JS → C++ → ArkTS → window.minimize() 的真实效果,不是贴图。

startWindowDrag 的拖拽跟随我用 uitest uiInput swipe 注入模拟不出来——startMoving 需要真实的鼠标按压-移动轨迹,注入的合成触摸事件带不动窗口。所以拖拽这一项我是用物理鼠标在真机上手动验证的:按住自定义标题栏中间的空白区域拖动,窗口跟着走;按住右侧三键区域,窗口纹丝不动。

3. 原理:标题栏到底归谁管

3.1 系统这一侧:窗口是路由单位

第一件要想清楚的事:窗口是路由单位,应用不是。窗口管理器(WMS / SceneBoard)为每个窗口绘制装饰(decor)——标题栏文字、图标、三键——这部分像素应用碰不到。应用能通过 window.Window 拿到的,是一组"控制开关",而不是"画笔":

系统 API(window.Window)作用本库暴露给 JS 的方法
setWindowDecorVisible(visible)原生标题栏显隐setNativeTitlebarVisible()
setWindowDecorHeight(height)原生标题栏高度([37, 112] vp)setNativeTitlebarHeight()
getWindowDecorHeight()读取当前高度getNativeTitlebarHeight()
setWindowTitleButtonVisible(max, min, close)三键显隐setTitleButtonVisible()
setDecorButtonStyle(style)三键间距/圆角/边距等样式setDecorButtonStyle()
getTitleButtonRect()三键区位置尺寸getTitleButtonRect()
setWindowLayoutFullScreen(enable)沉浸式全屏布局setImmersive()
startMoving() / stopMoving()进入/退出窗口拖拽跟随startWindowDrag() / stopWindowDrag()
minimize() / maximize() / recover()最小化/最大化/还原同名方法
terminateSelf()关闭窗口(终止 UIAbility)close()

自定义沉浸式标题栏的完整模型于是变成三步:藏掉系统画的,用普通 View 补上自己的,再把行为接回系统。拖拽这件事尤其典型——WindowTitlebarView 中间的空白区域自己不实现任何拖拽逻辑,只在 onTouchStart 时调一次 startMoving(),剩下的"指针移动 → 窗口跟随 → 抬手停止"全部由窗口管理器接管。

3.2 RNOH 这一侧:一个 TurboModule 要过三道门

RNOH 的 TurboModule 不是注册一次就完事。JS 侧的一个 TurboModuleRegistry.getEnforcing('WindowTitlebar'),背后要依次过三道门:

  1. JS 门(Spec):TypeScript 接口 NativeWindowTitlebar.ts,声明方法名、参数、返回值,是 codegen 的输入,也是 JS 侧的类型来源;
  2. C++ 门(Package + Spec):C++ 侧的 Package 向 TurboModuleFactory 声明"这个名字归我管",并给出一个带方法元数据(methodMap_)的 ArkTSTurboModule 子类——没有元数据,方法查找全部返回 undefined;
  3. ArkTS 门(RNPackage):ArkTS 侧的 RNPackage 用工厂 Map 注册真正的实现类,方法在这里落到 window.Window 的系统 API 上。

窗口事件的回传走另一条线,方向反过来:

事件系统回调JS 收到
窗口状态变化win.on('windowStatusChange')WindowTitlebarWindowStatusChange,`{status: ‘MAXIMIZE’
三键区变化win.on('windowTitleButtonRectChange')WindowTitlebarTitleButtonRectChange,{rect: {...}}
自由窗口模式win.on('freeWindowModeChange')WindowTitlebarFreeWindowModeChange,{isInFreeWindowMode}

ArkTS 侧通过 this.ctx.rnInstance.emitDeviceEvent(name, payload) 发出,JS 侧用 DeviceEventEmitter.addListener 接收。这两个细节——C++ 的 methodMap_ 和 ArkTS 的 emitDeviceEvent 挂在 rnInstance 上——决定了后面一半的排查方向。

4. 工程怎么搭

4.1 目录树

react-native-ohos-window-titlebar/
├── package.json                  # harmony.alias + codegenConfig 声明
├── src/                          # JS 侧(npm 包主体)
│   ├── NativeWindowTitlebar.ts   # Spec:方法签名 + 事件名 + 类型
│   ├── WindowTitlebarView.tsx    # 自定义标题栏 / 拖拽区 / 控制按钮(纯 JS)
│   └── index.ts                  # 出口:安全模块包装 + 事件 Hook
├── harmony/
│   └── window_titlebar/
│       ├── oh-package.json5      # 依赖 @rnoh/react-native-openharmony
│       └── src/main/ets/
│           ├── WindowTitlebarModule.ets   # ArkTS TurboModule 实现
│           └── WindowTitlebarPackage.ets  # ArkTS RNPackage 注册
├── example/                      # RN 测试工程
│   ├── App.tsx                   # 演示页(四分区)
│   ├── LibBridge.ts              # 库 import 的统一桥接层
│   └── harmony/
│       ├── entry/src/main/cpp/
│       │   ├── WindowTitlebarCppPackage.h  # C++ 侧注册(手写 Spec)
│       │   └── PackageProvider.cpp         # packages.push_back(...)
│       └── ...
└── docs/assets/                  # 真机截图

这次整理最关键的变化,是把"能跑"变成"能复用",三条边界划死:lib 不依赖任何页面(example 之外不 import App 层的东西);ArkTS 模块独立成 hap 内的 ets 目录,不跟 entry 混编;example 只走公共 API,App.tsx 对库的全部 import 收敛到一行 LibBridge.ts。

4.2 最小接入

JS 侧三步:探测 → 控制原生栏 → 听事件。

// App.tsx(节选)
import {
  WindowTitlebar, WindowTitlebarView, WindowDragRegion,
  isOhosPlatform, enableCustomImmersiveTitlebar, WindowTitlebarEvent,
} from 'react-native-ohos-window-titlebar';

// 1. 探测
const supported = await WindowTitlebar.isSupported();

// 2. 控制原生标题栏
await WindowTitlebar.setNativeTitlebarVisible(false);
await WindowTitlebar.setNativeTitlebarHeight(56);

// 3. 听窗口状态
DeviceEventEmitter.addListener(WindowTitlebarEvent.WINDOW_STATUS_CHANGE, p => {
  console.log(p.status); // 'MAXIMIZE' | 'MINIMIZE' | ...
});

// 4. 自定义沉浸式标题栏(内部已含拖拽区与三键)
<WindowTitlebarView title="RN 窗口标题栏 Demo" height={48} backgroundColor="#2f54eb" />

WindowTitlebar 本身做了跨平台兜底:TurboModuleRegistry.get('WindowTitlebar') 拿不到时自动降级为 no-op 实现,iOS/Android 上引入这个库不会崩,只是所有调用直接 resolve。

4.3 桥接协议

调用链协议很直白:JS 方法名 = C++ methodMap 键 = ArkTS 方法名,三者必须逐字符一致。异步方法统一走 Promise:

JS:   WindowTitlebar.getTitleButtonRect()
C++:  methodMap_["getTitleButtonRect"] → ArkTSTurboModule::callAsync
ArkTS: WindowTitlebarTurboModule.getTitleButtonRect() → win.getTitleButtonRect()
JS:   await → { right: 0, top: 0, width: 140, height: 47 }

事件方向相反,ArkTS 主动推:

ArkTS: win.on('windowStatusChange') → emitDeviceEvent('WindowTitlebarWindowStatusChange', {status})
JS:    DeviceEventEmitter.addListener → setLog(...)

容易被忽略的窗口期有两个:其一,WindowTitlebarTurboModule 在构造函数里就注册三个窗口监听,而此时窗口可能还没就绪,所以注册动作包在 getLastWindow().then(...) 里异步完成;其二,isSupported() 是同步 canIUse 直接 resolve,不依赖窗口对象,保证它在任何时机调用都不炸。

5. 把代码讲透

5.1 注册:RNOH 0.86 的工厂 Map 写法

RNOH 0.72.38+ 之后,ArkTS 侧 Package 的注册方式改成了"模块名 → 工厂函数"的 Map,由 RNOH 在 JS 侧 require 时按需创建:

// harmony/window_titlebar/src/main/ets/WindowTitlebarPackage.ets - WindowTitlebarPackage
export class WindowTitlebarPackage extends RNPackage {
  override getUITurboModuleFactoryByNameMap(): Map<
    string,
    (ctx: UITurboModuleContext) => TurboModule | null
  > {
    return new Map<string, (ctx: UITurboModuleContext) => TurboModule | null>()
      .set(WindowTitlebarTurboModule.NAME,
        (ctx: UITurboModuleContext) => new WindowTitlebarTurboModule(ctx));
  }

  // 本库不注册原生组件,但这个方法必须存在(RNOHPackage 结构要求)
  createWrappedCustomRNComponentBuilderByComponentNameMap():
    Map<string, WrappedBuilder<[ComponentBuilderContext]>> {
    return new Map();
  }
}

三个细节值得单独说。第一,注册走的是 getUITurboModuleFactoryByNameMap(UITurboModule),不是普通 TurboModule 工厂——因为我们的实现需要 uiAbilityContext 去拿窗口,普通工厂拿不到这个上下文。第二,createWrappedCustomRNComponentBuilderByComponentNameMap 返回空 Map 也要 override,RNOH 的 Package 结构会检查它。第三,这个 Package 要在 entry/src/main/ets/pages/Index.ets 或 RNOH 初始化处被加进 packages 列表。

5.2 桥接:C++ 侧必须给 methodMap_ 喂方法元数据

这是本次开发最值钱的一段。RNOH 的 ArkTSTurboModule C++ 基类不会把任意方法名自动派发给 ArkTS——它只认 methodMap_ 里登记过的方法。正常情况下这份元数据由 codegen 从 Spec 生成;codegen 跑不起来时(本工程如此),要手写一个等价的 Spec 子类:

// example/harmony/entry/src/main/cpp/WindowTitlebarCppPackage.h - WindowTitlebarSpec(节选)
class JSI_EXPORT WindowTitlebarSpec : public ArkTSTurboModule {
 public:
  WindowTitlebarSpec(ArkTSTurboModule::Context ctx, const std::string name)
      : ArkTSTurboModule(ctx, name) {
    methodMap_ = {
        ARK_ASYNC_METHOD_METADATA(isSupported, 0),
        ARK_ASYNC_METHOD_METADATA(isInFreeWindowMode, 0),
        ARK_ASYNC_METHOD_METADATA(setNativeTitlebarVisible, 1),
        ARK_ASYNC_METHOD_METADATA(setNativeTitlebarHeight, 1),
        ARK_ASYNC_METHOD_METADATA(getNativeTitlebarHeight, 0),
        ARK_ASYNC_METHOD_METADATA(setTitleButtonVisible, 3),
        ARK_ASYNC_METHOD_METADATA(setDecorButtonStyle, 1),
        ARK_ASYNC_METHOD_METADATA(getTitleButtonRect, 0),
        ARK_ASYNC_METHOD_METADATA(setImmersive, 1),
        ARK_ASYNC_METHOD_METADATA(startWindowDrag, 0),
        ARK_ASYNC_METHOD_METADATA(stopWindowDrag, 0),
        ARK_ASYNC_METHOD_METADATA(minimize, 0),
        ARK_ASYNC_METHOD_METADATA(maximize, 1),
        ARK_ASYNC_METHOD_METADATA(recover, 0),
        ARK_ASYNC_METHOD_METADATA(close, 0),
        ARK_METHOD_METADATA(addListener, 1),
        ARK_METHOD_METADATA(removeListeners, 1),
    };
  }
};

宏来自 RNOH/ArkTSTurboModule.h:ARK_ASYNC_METHOD_METADATA(名字, 参数个数) 生成一个转发到 callAsync 的调用器。这里有一个反直觉陷阱:方法元数据的第二个参数是"参数个数",不是"是否有返回值"——getTitleButtonRect() 虽然返回 Promise,参数个数仍是 0;写错了运行时不会报错,只会在调用时静默丢参。这个写法我是对着 RNOH 源码里 RNOHCorePackage/TurboModules/AccessibilityInfoTurboModule.cpp 抄的。

5.3 窗口控制:getLastWindow + 一次函数式的窗口获取

ArkTS 侧每个方法的骨架都一样:先拿到窗口,再调系统 API:

// harmony/window_titlebar/src/main/ets/WindowTitlebarModule.ets - WindowTitlebarTurboModule(节选)
private async getMainWindow(): Promise<window.Window> {
  return await window.getLastWindow(this.abilityContext);
}

setNativeTitlebarVisible(visible: boolean): Promise<void> {
  return this.getMainWindow().then((win: window.Window) => {
    win.setWindowDecorVisible(visible);
  });
}

maximize(immersive: boolean): Promise<void> {
  return this.getMainWindow().then((win: window.Window) => {
    const presentation: window.MaximizePresentation =
      immersive ? window.MaximizePresentation.ENTER_IMMERSIVE
                : window.MaximizePresentation.EXIT_IMMERSIVE;
    return win.maximize(presentation);
  });
}

三个细节值得单独说。第一,用 getLastWindow(context) 而不是在 onWindowStageCreate 里缓存主窗口引用——后者要在 UIAbility 生命周期里穿透到模块,耦合大;getLastWindow 每次拿当前最新的窗口,代价可接受。第二,maximize 的沉浸式参数是枚举 MaximizePresentation,JS 侧一个 boolean 映射到两个枚举值,true 对应 ENTER_IMMERSIVE(最大化并进入沉浸式)。第三,close() 不走 window 对象,而是 abilityContext.terminateSelf()——关闭自由窗口等价于终止承载它的 UIAbility。

5.4 拖拽区与点击控件:兄弟节点,不是嵌套

自定义标题栏最容易写错的是结构。系统原生标题栏的行为模型是"整条栏都能拖、按钮能点",用 RN 复刻时如果把控件嵌进拖拽区(或者反过来),触摸事件就会互相打架。WindowTitlebarView 的结构是:

// src/WindowTitlebarView.tsx - WindowTitlebarView(节选)
<View style={[styles.bar, { height, backgroundColor }, style]}>
  {titleIcon ? <Image source={titleIcon} style={styles.icon} /> : null}
  {leading}
  <Text style={[styles.title, { color: titleColor }]} numberOfLines={1}>
    {title}
  </Text>
  {/* 拖拽区域:占据剩余空间,与右侧控件互不嵌套 */}
  <WindowDragRegion />
  {actions}
  {showControls ? (
    <View style={styles.controls}>
      <WindowControlButton glyph="—" label="最小化" onPress={...} />
      <WindowControlButton glyph="❐" label="最大化" onPress={...} />
      <WindowControlButton glyph="✕" label="关闭" danger onPress={...} />
    </View>
  ) : null}
</View>

拖拽区本体只有几行:

// src/WindowTitlebarView.tsx - WindowDragRegion
export function WindowDragRegion({ style }: { style?: StyleProp<ViewStyle> }) {
  return (
    <View
      style={[{ flex: 1 }, style]}
      onTouchStart={() => {
        NativeWindowTitlebar.startWindowDrag().catch(() => {});
      }}
    />
  );
}

这里有一个很容易被忽略的窗口期:startMoving() 调用后,窗口进入"跟随指针"状态,直到系统收到停止指令或指针抬起。如果把它放进 onTouchMove,每次移动都调一次,反而会在系统侧排队产生怪异抖动;正确做法是只在 TouchDown 调一次。而右侧控件作为兄弟节点,Pressable 的手势天然不会冒泡进拖拽逻辑——这就是"让拖拽区域和关闭按钮各管各的"的全部实现,没有任何 hack。

5.5 事件回传:emitDeviceEvent 挂在 rnInstance 上,rect 没有 left

ArkTS 侧发事件时,我第一版写的是 this.ctx.emitDeviceEvent(...),编译直接不过。翻 RNOH 的 UITurboModuleContext 才确认:事件发射器挂在 this.ctx.rnInstance 上:

// harmony/window_titlebar/src/main/ets/WindowTitlebarModule.ets - registerWindowListeners(节选)
win.on('windowStatusChange', (status: window.WindowStatusType) => {
  const name: string = STATUS_NAMES[status as number] ?? 'UNDEFINED';
  this.ctx.rnInstance.emitDeviceEvent('WindowTitlebarWindowStatusChange', { status: name });
});
win.on('windowTitleButtonRectChange', (rect: window.TitleButtonRect) => {
  this.ctx.rnInstance.emitDeviceEvent('WindowTitlebarTitleButtonRectChange', {
    rect: { right: rect.right, top: rect.top, width: rect.width, height: rect.height }
  });
});

第二件事是 window.TitleButtonRect 的字段:它是 right/top/width/height,没有 left。我第一版 Spec 按 DOM 直觉写了 left,真机回传永远是 undefined。前端直觉在这里是错的——系统给的是"右边界到窗口右缘的距离 + 宽高",JS 侧要做避让时得自己算:left = windowWidth - right - width。降级说明:这套事件在非自由窗口模式下不会触发(窗口状态不变化),JS 侧要容忍监听注册后长时间收不到任何事件,不能拿"没收到事件"当"没注册成功"的判断依据。

6. 踩坑与经验

坑 1:codegen 不认 harmony.codegenConfig,Spec 变成一纸空文
我在 package.json 里按文档写了 harmony.codegenConfig(specPaths 指向 src/NativeWindowTitlebar.ts),构建后 C++ 侧的 RNOHGeneratedPackage.h 里始终没有 WindowTitlebar。查了 RNOH 仓库才确认这个工程的 codegen 链路对非标顶层字段不生效。

entry/src/main/cpp/generated/RNOHGeneratedPackage.h
  → 内容不含任何 WindowTitlebar 相关声明(codegen 静默跳过)

排查过程:一开始以为是 specPaths 路径写错,来回改了三次路径无效;后来直接看 codegen 产物目录,发现根本没有为我们的库生成任何文件。修复:放弃 codegen,手写 C++ Spec(第 5.2 节),ArkTS 侧手动注册。

点击演示区的最小化按钮后:窗口从桌面消失,最小化到任务栏

坑 2:红屏 Couldn't find Turbo Module ... on the CPP side。

Render Error: Couldn't find Turbo Module on the ArkTS side, name: 'WindowTitlebar'.
Couldn't find Turbo Module on the CPP side, name: 'WindowTitlebar' either.

ArkTS 侧注册了、C++ 侧没人认领这个名字。RNOH 的 TurboModuleProvider 先问 C++ 再问 ArkTS,两侧对不上就红屏。修复:在 PackageProvider.cpp 里 packages.push_back(std::make_shared<WindowTitlebarCppPackage>(ctx));,并在 CMakeLists 里链进头文件路径。

点击演示区的最小化按钮后:窗口从桌面消失,最小化到任务栏

**坑 3:真机红屏 undefined is not a function,报错在 JS,根因在 C++。**这是本次排查时间最长的一个。现象:

RNOH_JS: { [TypeError: undefined is not a function]
  componentStack: 'at App (bundle.harmony.js:92944:41) ...', isComponentError: true }

一开始以为是 react 没导出 useState(componentStack 指到 App 第一行 hooks),静态分析 bundle 里 react 模块链完全正确;--reset-cache 重打无效。后来在 App.tsx 里逐语句插桩 + catch 打印堆栈,才把抛错点钉死在 WindowTitlebar.isSupported() 这一行——报错被 React 归因到 App 组件(effect 错误的 componentStack 只显示宿主组件),误导了我整整三轮构建。根因:坑 2 的修复只解决了"模块能被找到",但手写的 ArkTSTurboModule 没填 methodMap_,C++ 基类对所有方法名返回 undefined。诊断手段是模块级探针:

const tm = require('react-native').TurboModuleRegistry.get('WindowTitlebar');
console.log(typeof tm.isSupported);            // 'undefined' ← 实锤
console.log(Object.getOwnPropertyNames(Object.getPrototypeOf(tm)));
// ['releaseAllCallbacks','releaseCallbacksByModule','getPendingCallbackCount'] ← 只有基类的三个方法

修复即第 5.2 节的 WindowTitlebarSpec。同一个报错文本可能来自两个完全不同的层;"模块能拿到"和"方法能调用"之间,还隔着一张方法元数据表。

点击演示区的最小化按钮后:窗口从桌面消失,最小化到任务栏

坑 4:Windows 260 字符路径限制,ninja 直接罢工。

ninja: error: Stat(.../example/harmony/entry/.cxx/.../很长的RNOH头文件路径...):
  Filename longer than 260 characters.

RN 工程的 node_modules 深路径 + RNOH 的 C++ 头文件,在默认的中文用户目录下超长。先试了 junction(mklink /J),结果 CMake 会把 junction 解析回真实路径,白搭。最终解法:robocopy 整个 example 到 C:\wtb\ 这种一级短路径下构建,产物再回拷。顺带一提,WorkBuddy 沙箱的 safe-delete 还会往删除路径上插钩子报 spawnSync genie-trash ETIMEDOUT,设 CODEBUDDY_SAFE_DELETE_ENABLED=0 关掉。

点击演示区的最小化按钮后:窗口从桌面消失,最小化到任务栏

坑 5:CMake 找不到 ffrt 的 C++ 侧。

CMake Error: Target "ffrt::ffrt_cpp" not found.
fatal error: ffrt/cpp/pattern/job_partner.h: No such file or directory

SDK 只带了 ffrt 的 C 接口和 libffrt.z.so,没有 C++ pattern 头,也没有 cmake 包。修复两步:CMakeLists 里手工造一个 INTERFACE IMPORTED 目标链 libffrt.z.so;缺的头文件按 RNOH 测试工程的 stub 方式本地补齐(提交的只是接口声明,不是实现)。

点击演示区的最小化按钮后:窗口从桌面消失,最小化到任务栏

坑 6:签名时 bundleName 对不上。

SignHap task: bundleName: com.example.xxx does not match SigningConfigs
  (profile bundleName: com.rnoh.awesomeproject)

用本机已有的调试签名材料,profile 绑定的是 com.rnoh.awesomeproject,而工程默认 bundleName 是别的。修复:AppScope/app.json5 的 bundleName 改成与 profile 一致。

坑 7:构建任务报 spawn java ENOENT。

PackageHap: spawn java ENOENT

JAVA_HOME 指到了不存在的路径(DevEco 装在 D 盘),而且 Git Bash 下 PATH 必须写 POSIX 形式(/d/Program Files/...),写 D:\... 不生效。顺带:example 里对三方库的 import 统一收敛到 LibBridge.ts 单行 re-export,绕开 RNOH metro 对入口文件多行 import 的改写问题。

坑 8:metro transform 缓存损坏,制造假线索。

Render Error: TypeError: undefined is not a function
  at anonymous (bundle.harmony.js:929:19)   ← (0, _react.useState)('Ready.')

排查坑 3 的过程中,有一轮真机报错显示 _react.useState 不是函数,静态分析 bundle 却完全正确。最后发现是 metro 的 transform 缓存损坏,--reset-cache 重打后该现象消失——但它和坑 3 的真实症状一模一样,浪费了我一轮构建。

7. 现在怎么用:从 三方库 到依赖

接入三步(以新 RNOH 工程为例):

# 1. JS 侧
npm install react-native-ohos-window-titlebar
# (或 file:/git 依赖)

# 2. ArkTS 侧:harmony/oh-package.json5 加依赖后
ohpm install

再在 entry/src/main/cpp/PackageProvider.cpp 注册 C++ 侧(本库随包附带 WindowTitlebarCppPackage.h,引入即可):

#include "WindowTitlebarCppPackage.h"
// createRNOHCPackage(ctx) 内:
packages.push_back(std::make_shared<rnoh::WindowTitlebarCppPackage>(ctx));

构建与安装:

cd example && npx react-native bundle --platform harmony --entry-file index.js \
  --bundle-output harmony/entry/src/main/resources/rawfile/bundle.harmony.js --dev false
cd harmony && hvigorw assembleHap --mode module -p product=default
hdc install -r entry-default-signed.hap

总结:

本次落地 react-native-ohos-window-titlebar 三方库,核心是厘清鸿蒙PC自由窗口里窗口装饰属于窗口管理器,应用无权直接绘制这个底层边界。整套方案依托RNOH的UITurboModule双端注册机制,把窗口原生控制API桥接至JS层,同时封装了开箱即用的自定义标题栏组件。实现上采用“隐藏系统装饰、RN视图补位、拖拽行为交还系统”的思路,通过兄弟节点布局天然隔离拖拽区与控制按钮,解决触摸事件冲突。开发过程中踩透了codegen失效、C++侧methodMap缺失、Windows长路径、签名不匹配等典型RNOH工程问题,也验证了这套模式在MateBook Pro等鸿蒙PC 2in1设备上的可用性,为RN在鸿蒙自由窗口场景下的沉浸式自定义标题栏提供可复用的实现范式。

鸿蒙PC自由窗口的标题栏开发,本质不是UI绘制,而是窗口权限与系统能力的对接。借助RNOH TurboModule完成JS、C++、ArkTS三层桥接,封装原生标题栏显隐、三键控制、窗口状态监听能力;自定义沉浸式标题栏依靠startMoving对接系统拖拽能力,用布局区分拖拽和点击区域。同时梳理了RNOH开发高频疑难坑,明确codegen失效时手写methodMap的方案,给同类鸿蒙PC端RN桌面组件开发提供参考。

很多开发者会误以为标题栏只是普通View,这也是鸿蒙自由窗口开发最容易踩的认知误区。窗口装饰由SceneBoard统一管理,应用只能控制开关,不能直接绘制。本库打通了RNOH TurboModule完整注册链路,补齐了窗口控制API的JS能力缺口,封装好组件降低业务接入成本。所有交互逻辑遵循系统原生规范,拖拽、窗口缩放、关闭行为和原生应用保持一致;同时沉淀一套真机调试排障思路,区分缓存问题、桥接层注册缺失、环境路径等不同报错根源,后续开发自由窗口类组件可以复用这套架构与排查经验。

Logo

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

更多推荐