社区里不少用 React Native 的同学，这两年都在关注 OpenHarmony 侧的适配进展。RNNOH（React Native for OpenHarmony）逐步补齐了桥接层和基础组件之后，大家发现真正卡脖子的其实是三方库：像地图、相机、推送这类重原生依赖的库，几乎都要逐个“鸿蒙化”。最近我接手了一个比较典型的适配任务，把社区里常用的小库 react-native-shake（摇一摇事件监听）完整迁移到了 OpenHarmony 平台。这个库本身不大，但麻雀虽小五脏俱全，它牵扯到传感器原生能力、事件桥接、JS API 兼容性、工程打包等一系列问题。整个过程走下来，对于理解 RN 库鸿蒙化的通用套路非常有帮助，也踩了不少坑，这里把完整思路和实操过程整理出来，给准备做同类适配的开发者做个参考。
1. 先把背景和需求拆清楚：为什么是 react-native-shake
1.1 一次“摇一摇需求”引出的适配任务
业务场景很简单：某 App 在 iOS 和 Android 端都接了社区的 react-native-shake，用户摇一摇手机就能唤起意见反馈页面。现在产品要求 OpenHarmony 端也要有同样的手势交互，用 RN 开发的业务代码不想再单独维护一套鸿蒙原生页面，所以最佳方案就是把 react-native-shake 的能力用 RNNOH 的方式“翻译”过来，让上层 JS 代码一行都不改。
这个需求在 RNNOH 生态里很常见。RNNOH 目前的兼容层已经能跑通大部分纯 JS 组件和基础 API，但凡是涉及原生硬件能力的库，比如传感器、蓝牙、NFC、定位，都需要做原生侧的迁移适配。react-native-shake 恰好是这类“原生能力型”三方库里最简单的一种：它只依赖一个传感器——加速度计，只做一件事——摇一摇手势识别，然后把事件抛给 JS。难度不大，但适配链路完整，非常适合当作模板来研究。
1.2 react-native-shake 原本是怎么工作的
在 iOS 侧，它基于 CoreMotion 的 accelerometer 数据做加速度变化检测；在 Android 侧，用的是 SensorManager 的 TYPE_ACCELEROMETER。原生侧持续读取三轴加速度数据，通过一个判定算法识别出“摇动”这个瞬态动作，然后通过 RN 的 DeviceEventEmitter 机制发送一个名为 shake 的事件。
JS 侧其实很简单，业务代码只需要：
import Shake from 'react-native-shake'; const subscription = Shake.addListener(() => { // 打开反馈弹窗 });也就是说，这个库对上层暴露的 API 非常收敛，本质就是一个事件订阅器。它的复杂度和核心价值全在原生侧的手势识别算法和桥接封装上。这就给鸿蒙化适配提供了一个很清晰的目标：把原生侧的传感器读取和算法判断换成 OpenHarmony 能用的实现，把事件桥接换成 RNNOH 能用的通道，JS API 保持不动即可。
1.3 鸿蒙化适配的本质，其实就是“换原生实现，留 JS 接口”
搞清楚了原库的结构，鸿蒙化的思路就非常直接了。可以理解成三件事：
- 第一，把 iOS 的 CoreMotion / Android 的 SensorManager 换成 OpenHarmony 的 @ohos.sensor 传感器接口；
- 第二，把 OC / Java 侧的事件发射逻辑，换成 RNNOH 能识别的 NativeModule 事件广播机制；
- 第三，把 package.json 里的入口指向新的鸿蒙实现，让上层业务引用到的对外 API 完全不变。
听起来不复杂，但实际动手时会发现，传感器数据怎么读、事件怎么穿过桥接层、怎么保证手势识别的准确率、怎么处理页面生命周期，每一环都有细节。下面我会先拆解摇一摇的核心算法和事件链路，再进入具体实现环节。
2. 摇一摇的核心机制与 RNNOH 事件桥接链路
2.1 为什么选加速度计而不选陀螺仪
摇一摇这个手势的物理本质，是手机在短时间内被快速、往复地施加位移和加速度。实现上有两种常见选择：加速度计（Accelerometer）和陀螺仪（Gyroscope）。
实际社区库普遍选加速度计，原因是：摇一摇产生的线性加速度变化非常剧烈，加速度计能直接捕捉到“冲击感”；而陀螺仪反映的是角速度变化，对旋转更敏感，但很多摇一摇动作其实并不伴随大幅旋转，单靠陀螺仪容易漏判。再加上加速度计是手机里最基础的传感器，覆盖面广、功耗低、API 成熟，所以 react-native-shake 原库和绝大多数同类实现都以加速度计作为唯一数据源。
鸿蒙化适配时，我也选择 OpenHarmony 的加速度传感器接口，保持和原库一致的技术路线。
2.2 摇一摇判定的核心算法：阈值、时间窗口、防抖
光把传感器数据读出来还不够，关键是“怎么判断这是一次摇动”。这里原库的思路非常经典，鸿蒙化时我也沿用了这套逻辑，只是在参数上做了微调。
首先，加速度计返回的是 x、y、z 三个轴上的加速度分量。静止状态下，三轴合成矢量的大小约等于重力加速度 g（9.8 m/s²）。摇动时，合成矢量会瞬间偏离这个基准值。所以判定逻辑的第一步，是计算三轴合加速度模值：
magnitude = sqrt(x*x + y*y + z*z) delta = abs(magnitude - 9.8)delta 越大，说明手机受到的附加加速度越强。我见过一些简单实现是“只要 delta 超过某个阈值就触发”，这样误报率极高，因为日常放手机、走路颠簸也可能出现瞬时抖动。
更稳妥的做法有三层过滤：
- 第一层是阈值判断：delta 要连续几次超过设定阈值，一般取 2.0 到 2.5 之间，相当于手机在某一瞬间承受了比重力还大两到三倍的加速度；
- 第二层是时间窗口：在 300ms 到 600ms 的窗口期内，至少命中 2 次以上，才算一次“有效的摇动模式”；
- 第三层是冷却时间：事件触发后进入 600ms 到 800ms 的冷却期，在冷却期内即使满足条件也直接忽略，避免一次摇动重复弹窗。
这三层参数配合下来，误报率会低很多。鸿蒙化时我在 ArkTS 侧用同样的思路实现了一个判定器，后面会放完整代码。
2.3 RN 原生事件是怎么送到 JS 的，RNNOH 有什么不同
在原生的 React Native 里，原生模块到 JS 的通路是这样的：原生侧发射事件 -> 事件进入 RN 的桥接层 -> DeviceEventEmitter / NativeEventEmitter 转发 -> JS 监听器回调执行。
在 RNNOH 里，这条链路结构依然存在，但底层的实现语言和通道换了。RNNOH 的核心是基于 RN 的 C++ 内核做的移植，原生侧可以是 C++ 写的 NativeModule，也可以是 ArkTS 写的模块。事件从原生侧进入 JS 侧时，需要通过 RNNOH 提供的事件发射接口来广播，而 JS 侧依然可以用 React Native 官方的 NativeEventEmitter 去监听。这意味着 JS 侧的使用方式完全不用改，RNNOH 会把兼容工作挡在桥接层之下。
我在做适配时，把传感器监听和摇一摇判定放在 ArkTS 侧实现，这样代码结构清晰，也符合 RNNOH 推荐的 ArkTS 优先原则。判定成功后，通过 ArkTS 侧持有的事件通道通知 C++/桥接层，再由 RN 事件机制广播给 JS。
2.4 鸿蒙化后的完整数据链路
经过适配后，一次完整的摇一摇事件链路是这样走的：
OpenHarmony 加速度传感器 -> ArkTS 读取三轴加速度数据 -> 摇一摇判定器计算模值、判断阈值与时间窗口 -> 判定成功，调用轻量级事件发射接口 -> RNNOH 桥接层收到事件，广播到 JS -> JS 侧 NativeEventEmitter 触发回调 -> 业务代码执行，比如弹出反馈页链路并不长，但每一环都要保证可靠。比如传感器回调频率是否够快、判定器的状态变量是否被正确重置、事件发射是否在正确的线程/队列中被调用，这些都会直接影响最终体验。
3. 鸿蒙化适配核心实操：从传感器到 JS API 全打通
3.1 工程结构与准备工作
在开始写代码之前，先确定适配包的工程组织方式。我的做法是：把原库 fork 一份，保留原有的 JS 层代码和 README，新增一个 harmony 目录，用来放 ArkTS 原生实现和对应的 RNNOH 桥接代码，最后通过 package.json 的 main 字段把入口切到鸿蒙实现上。
如果你们的项目是通过本地 patch 方式管理 RNNOH 三方库，也可以直接把改动做成独立的补丁集，跟着上游版本走，后续升级时好合并。但不管哪种方式，都需要先确认三点：
- 当前 RNNOH 版本对应的 React Native 版本（0.72 还是 0.73，接口会有差异）；
- OpenHarmony SDK 版本和传感器接口形态（@ohos.sensor 老接口还是 @kit.SensorServiceKit 新接口）；
- 工程量构建系统是否支持 ArkTS 原生模块的编译接入。
这三项不确认好，后面写代码很可能会白费功夫。
3.2 权限声明：加速度传感器也要声明
一个很容易被忽略的细节是权限声明。OpenHarmony 里加速度传感器属于普通级（normal level）权限，不需要弹窗向用户申请授权，但它依然要在模块配置里显式声明，否则运行时拿不到数据。
在 RNNOH 工程的模块配置文件 module.json5 里，需要添加：
{ "module": { "name": "entry", "requestPermissions": [ { "name": "ohos.permission.ACCELEROMETER" } ] } }这个权限声明不加，传感器接口不会报错，但回调永远不触发，排查起来很容易误判成代码逻辑问题。这是我这次适配中第一个实际踩到的坑，后面排查章节也会专门讲到。
3.3 ArkTS 侧传感器监听的实现
接下来是核心部分：在 ArkTS 侧读取加速度传感器数据。这里用到了 OpenHarmony 的 sensor 模块。以当前主流 SDK 的推荐写法为例：
import { sensor } from '@kit.SensorServiceKit'; // 老版本 SDK 也可以这样引入： // import sensor from '@ohos.sensor'; let shakeCallback: sensor.SensorCallback = (data: sensor.SensorData) => { // data 是加速度传感器数据，包含 x、y、z 分量 }; // 注册加速度传感器监听 sensor.on(sensor.SensorId.ACCELEROMETER, shakeCallback, { interval: 'ui' });这里有两个参数需要解释一下。
第一个是传感器类型。SensorId.ACCELEROMETER 就是加速度计，返回的 data 对象里，x、y、z 单位是 m/s²，通常已经包含了重力分量。需要特别注意不同版本的 SDK 返回字段可能略有差异，有的版本是 accelerationX / accelerationY / accelerationZ，有的直接是 x / y / z，按实际调试结果来取。
第二个是采样间隔。interval 参数我建议用 'ui'，也就是 UI 帧率级别的采样频率，大概 60Hz 左右。摇一摇动作本身持续时间只有几百毫秒，采样太低容易漏掉关键峰值，采样太高会增加无谓的功耗开销。实际测试下来，'ui' 这个档位对摇一摇识别是足够且均衡的。
3.4 摇一摇判定器：阈值、窗口、冷却
传感器回调会非常频繁地触发，我们不希望在回调里写太多复杂逻辑，所以我把判定逻辑单独封装成一个类：
class ShakeDetector { private triggerCount = 0; private lastTriggerTime = 0; private lastEmitTime = 0; private readonly threshold = 2.2; private readonly windowMs = 400; private readonly coolDownMs = 700; public onSensorData(x: number, y: number, z: number): boolean { const magnitude = Math.sqrt(x * x + y * y + z * z); const delta = Math.abs(magnitude - 9.8); const now = Date.now(); // 冷却期内直接忽略 if (now - this.lastEmitTime < this.coolDownMs) { return false; } if (delta > this.threshold) { if (now - this.lastTriggerTime > this.windowMs) { this.triggerCount = 1; this.lastTriggerTime = now; } else { this.triggerCount++; this.lastTriggerTime = now; } if (this.triggerCount >= 2) { this.triggerCount = 0; this.lastEmitTime = now; return true; } } else { // 如果长时间没有连续命中，重置计数 if (now - this.lastTriggerTime > this.windowMs) { this.triggerCount = 0; } } return false; } public reset() { this.triggerCount = 0; this.lastTriggerTime = 0; this.lastEmitTime = 0; } }这里的几个参数数值，我解释一下依据：
- threshold 取 2.2，也就是说三轴合加速度与重力的差要超过 2.2 m/s²。大多数人快速摇动手机时，这个差值能轻松达到 4 到 6，所以我留了比较多的余量来防误报；
- windowMs 取 400ms，在这个时间窗口内要连续两次命中阈值。单人完成一次“摇一摇”动作的完整周期大约在 200ms 到 500ms，400ms 窗口能抓住这个节奏，又不会把日常颠簸误判成摇动；
- coolDownMs 取 700ms，保证一次完整摇动只触发一次事件，避免同一个动作连续弹多次反馈框。
实际业务中如果觉得灵敏度不对，优先调 threshold，其次是 windowMs，冷却时间一般不用动。
3.5 事件发射：把 shake 事件送进 RN 桥接层
传感器数据和判定逻辑都在 ArkTS 侧跑通了，接下来最技术性的环节就是把事件送进 JS。RNNOH 中事件发射的常见方式有两种：
第一种是使用 CxxModule。在 C++ 层实现一个 NativeModule，模块里暴露事件名常量，并且提供一个 emit 方法供 ArkTS 侧调用。CxxModule 是 RNNOH 兼容性最好的一种桥接方式，因为它和 RN 内核是同构的，事件发射路径最短、最稳定。
第二种是通过自定义的 TurboModule 来实现。虽然 RNNOH 对 TurboMode 的支持逐步在完善，但如果你们项目还不是 TurboMode 模式，反而会增加复杂度。所以我在这次适配里优先选择 CxxModule 方式。
CxxModule 的框架大致是这样的（示意代码，具体 API 以你所用 RNNOH 版本的头文件为准）：
class ShakeModule : public facebook::react::CxxModule { public: ShakeModule(std::unique_ptr<facebook::react::NativeMethodCallHandler> handler) : handler_(std::move(handler)) {} static std::string getName() { return "ShakeModule"; } std::map<std::string, folly::dynamic> getConstants() override { return {{"ShakeEventName", "onShake"}}; } std::vector<Method> getMethods() override { return { Method( "emitShake", [this](folly::dynamic args, Callback cb) { // 这里会由 ArkTS 侧调用，触发一次广播 handler_->callMethod( "ShakeModule", "emitDeviceEvent", folly::dynamic::array("onShake", folly::dynamic::object())); }, AsyncTag) }; } private: std::unique_ptr<facebook::react::NativeMethodCallHandler> handler_; };ArkTS 侧在判定器返回 true 时，只需要调用 CxxModule 暴露的 emitShake 方法即可。具体调用方式取决于你的工程怎么把 CxxModule 的实例传给 ArkTS 侧，一般是通过一个全局单例或者绑定在原生入口处。
如果你用的 RNNOH 版本不支持这种写法，也可以退而求其次，在 ArkTS 侧通过 NativeEventEmitter 直接向 JS 广播事件。具体 API 各版本略有出入，但思路一致：原生侧有一个能拿到 JS 事件发射器引用的通道，判定成功后调用广播方法，JS 侧监听同名事件即可。
3.6 JS 侧封装：保持原库 API 兼容
JS 侧的封装是整个适配里最需要“克制”的部分。原库暴露什么 API，我们鸿蒙化后就应该原样保留什么 API，上层业务的调用方式不能变。我在适配包的 index.js 里做了这样一层封装：
import { NativeEventEmitter, NativeModules } from 'react-native'; const ShakeEmitter = new NativeEventEmitter(NativeModules.ShakeModule); class Shake { static addListener(callback) { return ShakeEmitter.addListener('onShake', callback); } static removeListener(listener) { ShakeEmitter.removeListener('onShake', listener); } } export default Shake;唯一的差异是，我们把事件名常量统一成 onShake，并且从 ShakeModule 里导出。这样处理之后，业务代码里原来的 addListener 调用完全不需要改动，直接 upgrade 依赖就能跑。
还有一个细节要注意：事件发射器和监听器的注册时机。RN 里 NativeEventEmitter 在 NativeModule 尚未加载完成时创建，可能导致 emit 时事件丢失。所以我在适配包里做了个小处理——在模块真正 ready 之后才允许注册监听，如果事件在监听注册前已经发生，就丢弃不用缓存。这个对摇一摇场景是合理的，用户不可能在页面刚打开几十毫秒内就摇动触发功能。
3.7 真机验证与验收
代码写完只是一个开始，真正能证明适配成功的是真机效果。鸿蒙模拟器对加速度传感器的支持很有限，很多模拟器压根不返回真实传感器数据，所以验收环节我强烈建议用真机跑。
验证步骤一般是这样：
- 第一步，先做一个最简 Demo 页面，页面上显示“摇一摇监听已就绪”，摇动后日志输出一条 shake 事件；
- 第二步，确认事件触发次数是否符合预期，连续摇三次，看是否每次都能稳定触发，且一次摇动不会触发多次；
- 第三步，测试误报场景：手机平放在桌上、正常走路手持、从口袋里拿出来，分别停留 10 秒，确认没有误触发；
- 第四步，测试页面销毁后是否还能收到事件——如果还能收到，说明未释放传感器监听，这是一个典型 bug，后面排查部分会展开。
通过这四步，基本上可以把一个摇一摇库的核心质量验收掉。
4. 踩过的坑与排查实录
4.1 真机收不到事件，先从三个方向查
这是我做 RN 原生模块适配时遇到频率最高的问题：代码都写好了，真机跑起来页面正常，但摇动手机会发现 JS 侧日志没有任何输出。
排查这种问题，我一般按下面的顺序来：
- 第一，查权限声明。module.json5 里的 ohos.permission.ACCELEROMETER 有没有加。这个权限不加，传感器 API 不报错、不提示，就像一条暗河，你根本不知道问题在哪。我在第一次调试时就卡在这里大半个小时，最后无意间发现权限列表里没有这一项，加上就好了。
- 第二，查模块注册。CxxModule 有没有在 RNNOH 的包管理器里正确注册。某些 RNNOH 版本对模块名大小写敏感，注册名和 JS 侧 NativeModules 里取的名称不一致，事件发射接口拿到的模块就是 undefined。
- 第三，查监听注册时机。JS 侧是否在模块 ready 之前就注册了监听，导致原生侧事件广播出去后找不到接收者。这个属于时序问题，可以在 addListener 之前加一个延时或者把监听放在页面的 useEffect/componentDidMount 里注册，基本可以规避。
这三个方向覆盖了百分之八十的“收不到事件”问题。
4.2 模拟器上无法触发，别跟它死磕
前面说过，模拟器的传感器能力非常有限。我在项目里遇到过模拟器上摇一摇完全没反应，但同一套代码换真机马上就能触发的情况。
这不是代码的锅，是模拟器对硬件传感器的模拟支持不完整。尤其是鸿蒙生态的模拟器，目前对传感器数据的模拟策略还在完善中，很多版本直接不提供加速度计数据。
所以调试时我的建议是：先用日志打印确认传感器回调有没有进来。在 ArkTS 侧的 onSensorData 里加一个 console.log，如果模拟器上这个日志完全不出现，那就别再调算法参数了，尽快切换到真机调试。真机才是摇一摇场景下唯一可信的验证环境。
4.3 灵敏度不是越高越好，调参要相信“手感”
另一个常见问题是：库适配好了，也收到事件了，但用户反馈“太灵敏了，随便动一下手机就触发”。
这类问题的核心在于 threshold 和 windowMs 的取值。我见过有人把 threshold 调到 1.0，结果手机放在桌上来一条消息震动一下就弹窗，体验非常糟糕。调参时建议记住一个原则：摇一摇是一个“大动作”，宁可稍微迟钝一点，也不要频繁误报。
我最终的参数组合是 threshold 2.2、windowMs 400ms、触发次数 2 次、冷却 700ms。这个组合在多种真机上测试过，包括不同传感器灵敏度的机型，误报率都很低。不同项目如果对灵敏度有特殊要求，可以在 ShakeDetector 里把参数暴露出来，让业务侧可配置。但要给业务侧设定合理的范围，比如 threshold 不要低于 1.8，否则很容易把“走路晃动”也识别成摇一摇。
4.4 页面销毁后还收到事件，生命周期管理别忽略
这个坑是原生模块适配里很典型的问题：页面 A 注册了摇一摇监听，页面 B 也注册了，页面 A 销毁后摇一摇，页面 B 事件触发了两次。
原因是传感器监听没有在页面销毁时释放，导致同一份传感器数据被多个页面实例重复消费。ArkTS 侧正确做法是这样：
private register() { sensor.on(sensor.SensorId.ACCELEROMETER, this.shakeCallback, { interval: 'ui' }); } private unregister() { sensor.off(sensor.SensorId.ACCELEROMETER, this.shakeCallback); this.detector.reset(); }同时 JS 侧在页面卸载时要调用 Shake.removeListener 解除订阅。两端都要做好清理，单靠一端释放，另一端还是会挂着。
另外还要注意 App 前后台切换。App 退到后台后，传感器回调依然会触发，白白耗电。我一般会在声明周期里做一次统一处理：App 进入后台时 unregister，回到前台时重新 register。
4.5 多个模块同时抢传感器，容易互相干扰
还有一种比较隐蔽的情况：同一个 RNNOH 工程里，如果其他功能模块也监听了加速度传感器（比如步数统计、横竖屏检测），那么摇一摇判断可能会被“降频”影响。
OpenHarmony 的传感器机制对同一类型传感器的多个监听者，采样频率倾向于取最大请求值，但如果某个模块的监听实现有问题，比如用较低频率注册后又长期不释放，就可能拖低全局的传感器数据回调频率，导致摇一摇检测在关键时刻拿不到足够密集的采样点。
遇到这类问题，常规排查方案是：把其他传感器监听临时关掉，只保留摇一摇监听，看问题是否消失。如果确实是传感器抢占导致的，建议统一由一个专用模块管理传感器资源，其他模块向它请求数据，而不是各自独立注册。这也是适配多个传感器类三方库时值得提前做的架构规划。
5. 从 shake 出发，给后续鸿蒙化适配的一些参考
5.1 一个小库撑起的适配模板
做完整个 react-native-shake 鸿蒙化之后，我最大的感受是：这个库虽然小，但它把原生能力型三方库的适配路径完整走了一遍。传感器接入、算法移植、桥接层通信、事件广播、JS API 兼容、生命周期管理、调参与排错，一个不落。以后再做类似的三方库迁移，比如磁力计指南针、光线传感器自动亮度、陀螺仪手势识别，完全可以复用这套模板。
模板的关键点其实就两条。
第一条是“原生能力收口”。把传感器读取和手势判定全部收敛在原生侧，JS 侧永远只拿到一个可订阅的事件流。这样上层业务是 RN 也好、原生也好，都不会被底层算法细节干扰。
第二条是“桥接层保持稳定”。只要 CxxModule 的注册名和事件名固定下来，JS 侧的封装逻辑基本不会变，后续 OpenHarmony SDK 升级时，最多只改 ArkTS 侧传感器 API，桥接层和 JS 层都不动，维护成本非常低。
5.2 参数和能力的扩展空间
同样的检测框架，把 threshold 换成低阈值，把 windowMs 换成长时间窗口，就能实现“敲击检测”或者“拿起手机”等动作识别。把加速度计换成陀螺仪，又能拓展出旋转手势。所以 shaker 的适配价值并不只在摇一摇本身，它是一整套“基于传感器的手势识别原生化能力”的雏形。
如果项目后续要把这类能力开放给多个页面复用，可以考虑在适配包之上再做一层封装：原生侧只负责原始动作识别，JS 侧提供 ShakeSubscription 管理，并按页面维度自动注册和注销监听，这样业务侧就不用自己处理生命周期了。
5.3 保持与上游同步
最后提一个和开源协作相关的实践：鸿蒙化适配的代码最好做成独立 patch 或独立分支，不要直接改死在上游版本里。我建议每次适配时把改动集中到一个清晰地 diff 集合中，包括 ArkTS 传感器监听、CxxModule 桥接、JS 封装三部分，并写清楚适配基线的 RNNOH 版本和 OpenHarmony SDK 版本。这样上游社区更新时，可以把基础库升级和新适配合入分开做，不至于因为一次上游升级就把鸿蒙化代码冲掉。
我个人做完这次 shake 适配验证后，团队里已经把这套路径整理成了内部的三方库鸿蒙化参考文档。下一个目标是拿一个稍微复杂的库做练习，比如带 UI 的原生弹窗组件或二维码扫描库，把原生视图的桥接也走通。如果你们也在做 RNNOH 相关适配，建议从 shake 这种小库热身，跑通流程后再啃硬骨头，效率会高很多。
