前阵子把公司的 React Native 应用往 openHarmony 设备上迁移,最折磨我的不是环境搭建,也不是 NAPI 桥接,而是一个看起来很小的交互问题:页面里有一张可双指缩放的地图卡片,外层套着一个纵向滚动的列表。同样的页面在 Android 上跑得好好的,换到 rk3568 开发板上之后,双指缩放一触发,外层列表就跟着上下抖,手指松开后偶尔还会出现一段“幽灵滚动”,必须退出页面重进才能恢复。排查了整整两天,最后把系统手势、ArkUI 容器手势、RN JS 手势这三层的关系理清楚,才算真正解决。
这个问题的背后,其实牵出了 openHarmony 上 React Native 应用三层手势体系的博弈。我结合自己在 openHarmony 的 rk3568 设备上做 RN 适配的完整经历,把从设备树选型到 NAPI 桥接、再到 JS 侧手势仲裁的整条链路一并分享出来。文章适合正在把 RN 应用迁移到 openHarmony、或者已经完成适配但被手势冲突卡住的人参考。里面没有太多高大上的架构理论,全是能直接落到真机上的步骤和结论。
1. 从设备树到 NAPI:openHarmony 上 RN 手势冲突的背景板
1.1 rk3568 设备树到底咋选
很多人在 openHarmony 源码根目录下用 hb set 选择产品时,看到一堆 rk3568 相关的配置项就懵了。这其实不是设备树选择的问题,而是产品配置(product)与板级设备树(dts)之间的对应关系问题。rk3568 系列在社区里能见到的开发板很多:润和的 DAYU200、触觉智能的 IDO-EVB3568、T-Core,还有一些工控核心板。它们的 SoC 都是 RK3568,但外设引脚、触摸屏型号、屏幕分辨率都不一样。
选型的正确思路不是去背每个板子的 dts 文件名,而是先确认你跑的系统镜像是基于哪一套产品配置编译出来的。OpenHarmony 标准系统的编译产物里,out/<product>/packages/phone/system/etc/ 下能直接看到启动了哪个 dtb;在源码仓里,vendor/xxx 下对应产品的 config.json 会指定 device board 和 kernel 方案。如果你只是拿 rk3568 开发板做应用验证,最省事的方式是选择官方或板厂提供的标准产品配置,比如常见的 rk3568 标准系统配置,再根据实际板子的屏幕分辨率去调整 dts 的显示节点。
我建议开发早期就把触控相关的外设先调通。有人在 dts 里把触控 IC 节点给屏蔽了,结果桌面滑动正常、应用内手势全部“失灵”,现象跟手势冲突非常像,容易把排查方向带偏。可以先执行下面的命令,确认触摸控制器节点在系统里是可见的:
bash复制ls /sys/bus/i2c/devices/
cat /proc/bus/input/devices | grep -i touch
能看到对应的触摸控制器节点,再往下谈手势冲突才靠谱。
1.2 RN for OpenHarmony 的运行链路速览
React Native 在 openHarmony 上并不是套个 WebView 那么简单,社区维护的 React Native for OpenHarmony 延续了 RN 的 C++ 跨平台核心,UI 部分通过 NAPI 映射到 ArkUI 的原生能力上。也就是说,JS 侧写的 <View>、<ScrollView> 并不是直接由 ArkUI 渲染,而是 RN 的 C++ Core 通过 JSI/TurboModule 接口,再调用 OpenHarmony 的 NAPI 能力去创建 ArkUI 节点。
这条链路对手势意味着什么?意味着一个触摸事件要经过:触控驱动 -> ArkUI 手势识别 -> NAPI 回调 -> RN C++ 事件分发 -> JS 侧 PanResponder/GestureHandler。任何一个节点没有把事件标记成“已消费”,下一个节点就会认为自己也可以响应。我在真机上遇到的双指缩放和列表滚动冲突,本质上就是这条链路上的“双重消费”。
理解这个背景之后,解决方案就自然分成两条路:要么在 ArkUI 原生侧提前拦截,要么在 JS 侧做统一的仲裁分发。下面分别展开讲。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 三层手势模型:冲突的根子出在“谁先响应”
2.1 第一层:OHOS 系统级手势
系统级手势包括状态栏下拉、边缘滑动返回、三指截屏等。在 rk3568 的触摸屏设备上,尤其容易出问题的是侧边滑动返回手势。RN 应用默认是全屏窗口,如果页面里有一个横向滑动的组件(比如轮播图或横向列表),系统边缘手势很容易和它抢事件。
禁掉系统手势不是一个好选择,会影响系统交互的一致性。我当时的做法是给横滑组件设置安全区约束,让出屏幕边缘区域,把横向滑动组件的可触达范围限定在安全区以内。这是一层很容易被忽略的解决维度:先把系统手势的干扰范围隔离掉,再处理原生容器手势和 JS 手势的冲突,问题能简化不少。
2.2 第二层:ArkUI 容器手势
ArkUI 的滚动容器(Scroll、List、Swiper)自带手势识别,它们会对手势方向做首轮判定。比如纵向 Scroll 在识别到水平移动超过阈值后,会选择放弃识别,把事件交出去。问题在于,这个“放弃”动作在桥接到 RN 时,往往没有把状态完整同步过去。
举一个我实际遇到的例子:
