1. 为什么要把 react-native-shake 搬进 OpenHarmony
1.1 摇一摇这个交互在 App 里到底承担什么角色
做 React Native 鸿蒙化适配这段时间，我碰到最多的需求不是“把页面跑起来”，而是“把那个能用的小功能库搬过去”。react-native-shake 就是典型代表。名字听着很轻量——“摇一摇事件监听”，实际用起来，摇一摇这个动作在业务里的分量远比想象中重。
最常见的场景是入口触发。很多内容类 App 用摇一摇隐藏彩蛋、换肤、底部弹层，甚至在一些工具类产品里，摇一摇直接关联“刷新”、“反馈”、“报Bug”。这类交互的好处是无侵入，不需要用户在界面上找按钮，手机晃动一下，事件就来了。在 OpenHarmony 设备逐渐进入实际商用项目以后，原先跑在 Android/iOS 上的 RN 应用要做迁移，摇一摇这个能力如果保不住，业务方就得重新设计入口，体验就打折扣了。
react-native-shake 这个库在原生态里解决的正是“跨平台摇一摇事件统一封装”。它屏蔽了 Android 传感器监听和 iOS 的 UIEvent/运动传感器差异，对外暴露一个简单的事件监听接口。但在 OpenHarmony 的 RN 兼容层里，它没有对应的原生实现，JS 代码直接 import 进来只能拿到一个空壳。所以我们需要做一次完整的鸿蒙化改造。
这里要提前说清楚：鸿蒙化一个 RN 三方库，不是改几行 JS 就能完事，而是要重新实现原生侧能力、打通桥接通道，再封装回与原库一致的 JS API。react-native-shake 规模不大，但涉及传感器、事件总线、生命周期管理，用来当鸿蒙化改造成样本正好合适。
1.2 react-native-shake 原本做了什么
原库的核心逻辑可以拆成四块：
第一，传感器注册。Android 侧一般用 SensorManager 注册加速度计，iOS 侧用 CoreMotion 的 accelerometer 数据。第二，摇动判定。拿到连续多个采样点的三轴加速度数据，通过幅度、频率、持续时间综合判断用户是否“摇”了。第三，事件通知。判定成功后向 JS 侧发送一个 shake 事件。第四，资源释放。页面卸载后移除传感器监听，避免后台持续耗电。
原库的 JS API 并不复杂，核心就两个能力：注册监听和移除监听。比如 react-native-shake 的经典用法是：
import Shake from 'react-native-shake'; const subscription = Shake.addListener('shake', () => { console.log('手机被摇了'); }); // 卸载页面时 subscription.remove();有些版本还兼容 addEventListener/removeEventListener 写法。鸿蒙化改造时，最好把这些 API 形式都保留，这样业务侧代码不用大改。如果改接口命名，业务方就得全量替换调用点，那这个“鸿蒙化”就名不副实了。
1.3 鸿蒙化改造的真正难点
难点不在传感器读取本身，OpenHarmony 的传感器 API 其实很直观，难点在两点。
第一，事件通道怎么打通。RN 的 JS 侧和原生侧是两套运行时，原库在 Android 上通过原生模块发送事件到 RCTDeviceEventEmitter，JS 侧再订阅。OpenHarmony 的 RN 兼容层同样有自己的桥接机制，但接口体系和 Android 不完全一致，需要按照 OpenHarmony 侧的模块规范去注册和发送事件。
第二，摇动检测算法需要重新调参。原库在 Android 上积累的阈值参数是基于主流 Android 设备传感器特性统计出来的，OpenHarmony 设备用的传感器芯片和采样频率范围不同，直接照搬会出现两个问题：要么太灵敏，放口袋里走两步就疯狂触发；要么太迟钝，甩断手都没反应。所以算法层面不能只翻译，还要做适配和可配置化。
这两个难点解决完，整个库基本就活了。下面我把桥接机制、底层实现、实操步骤和踩坑记录全部展开。
2. 鸿蒙化 RN 三方库的桥接机制与整体设计
2.1 理解 RN 与 OpenHarmony 之间的原生模块通道
React Native 的理论模型是三端三套代码：JS 写业务、原生写平台能力、中间靠桥接通信。OpenHarmony 上的 RN 兼容层延续了这个模型。JS 侧通过 requireNativeModule 或 TurboModule 拿到原生模块的引用，调用原生暴露的方法；原生侧可以处理完数据后，再通过事件机制主动向 JS 侧推送消息。
所以我拿到一个三方库，第一件事就是去翻它的原生代码，看它用到了哪些原生能力、暴露了哪些方法、发了哪些事件。react-native-shake 比较单纯：它没有需要 JS 参数调用的方法，只有一个持续发生的事件。这就意味着改造重心在“原生侧监听传感器并主动 emit 事件”，而不是复杂的双向调用。
OpenHarmony 的 RN 兼容层对原生模块的承载形式和 Android 的 ReactContextBaseJavaModule 不完全一样，普遍做法是用 ArkTS 写一个继承 TurboModule 的类，再通过组件包注册到 RN 运行环境。整个通道的职责很清楚：原生模块负责跟传感器系统服务打交道，JS 侧只感知事件。
2.2 一次标准的鸿蒙化改造流程
我把整个流程拆成了六步，后面每一段都会落到具体操作。
第一步，建立鸿蒙化目录。在包的根目录下单独放一个 harmony/ 目录，里面放 ArkTS 原生代码，和已有的 android/、ios/ 并列。第二步，在 package.json 里声明 harmony 入口，让 RN 的自动链接工具能发现原生部分。第三步，写原生 TurboModule 类，实现传感器注册、摇动检测、事件发送。第四步，写模块包装类，把它注册到 RN 的模块列表。第五步，写 JS 侧 TS 封装，保持与原库相同的导出名和方法签名。第六步，在示例工程里真机联调，观察传感器事件是否稳定送达 JS。
这里面最容易忽略的是第三步和第五步之间的事件名约定。原生 emit 的事件名必须和 JS 侧监听的事件名完全一致，比如统一用 "ShakeEvent" 或 "shake"。如果原生发送 "shake"、JS 监听 "ShakeEvent"，哪怕其他代码全对，也收不到消息。
2.3 设计取舍：事件通道应该选哪一条
RN 的原生模块往 JS 侧推送事件，常见方式有两种：一种是通过 RCTDeviceEventEmitter（对应 OpenHarmony 侧的 DeviceEventEmitter），一种是通过 CALLBACK 或 promise 的方式回传。
摇一摇这种“未知时刻发生、可能重复多次”的事件，天然适合 DeviceEventEmitter。它是 RN 事件机制里专门为持续异步事件设计的通道，JS 侧可以多个监听者同时订阅，也方便 remove。promise 方式适合一次性请求，比如“查询当前设备剩余电量”，摇一摇显然不适用。
还有一个取舍发生在原生模块内部。传感器回调频率通常很高，尤其是游戏模式采样间隔可能只有 20ms 甚至更短。如果把这个频率全部转发到 JS 侧，JS 线程会瞬间被事件风暴淹没。更好的做法是在原生侧完成摇动判定，判定成功的瞬间再 emit 事件。这样 JS 收到的是一小簇事件，而不是高频原始数据。这个设计看起来简单，但对事件的稳定性和性能影响非常大。
3. 摇一摇事件监听的底层实现细节
3.1 加速度计数据怎么采、怎么算
OpenHarmony 上读取加速度计，核心是传感器服务。一般在 ArkTS 里通过 @ohos.sensor 或系统 Kit 的传感器模块调用。第一步是获取加速度计监听，指定回调函数和采样间隔。
以我习惯的写法为例：
import { sensor } from '@kit.SensorServiceKit'; sensor.on(sensor.SensorId.ACCELEROMETER, onSensorDataChanged, { interval: sensor.SensorInterval.GAME, });这里 SensorInterval.GAME 对应较短的采样周期，适合摇动这类需要捕捉快速变化的场景。callback 里拿到的是三个轴的加速度分量，单位是米每二次方秒。静止平放时，理论上 x 和 y 接近 0，z 接近 9.8（重力加速度）。实际设备会有抖动，所以不能拿单帧数据做判断。
我通常会在回调里先做一次“三轴合成幅度”计算：
function onSensorDataChanged(data: sensor.AccelerometerResponse) { const magnitude = Math.sqrt(data.x * data.x + data.y * data.y + data.z * data.z); // magnitude 就是当前合加速度 }为什么要合成？因为手机在手里可以是任意姿态，正握、横握、倒握都可能。假如只盯着 z 轴变化，横向摇动时 z 轴可能变化不明显，误判概率会很高。合加速度把三轴信息收拢成一个标量，再用这个标量和重力基准值比较，就能判断“是否偏离了静止状态”。
3.2 摇动判定算法与阈值调优方法
拿到合加速度 magnitude 之后，最简单的判定逻辑是计算它和重力基准值之间的差值：
const gravity = 9.81; const delta = Math.abs(magnitude - gravity); if (delta > threshold) { // 认为可能发生了摇动 }threshold 取多少合适？这是一个纯经验活。我最初直接照原库用 2.0，结果真机上随便抬手就触发，因为抬手一瞬间 z 轴会先变负再变正，合成幅度的波动很容易超过 2.0。后来调成 2.8，正常走动时偶尔还会触发。最终我采用的方案不是单一阈值，而是“阈值+连续帧数+最小间隔”三重条件：
第一，delta 值超过阈值，表示当前采样点加速度偏离明显。第二，连续三到五个采样点都超阈值，才认为是一个有效的摇动动作，避免单点毛刺。第三，本次摇动与上一次有效摇动之间至少间隔 500ms，防止一次甩动被重复计数。
代码如下：
let lastShakeTime = 0; let exceedCount = 0; const threshold = 2.5; const minExceedCount = 3; const minShakeInterval = 500; function onSensorDataChanged(data: sensor.AccelerometerResponse) { const magnitude = Math.sqrt(data.x * data.x + data.y * data.y + data.z * data.z); const delta = Math.abs(magnitude - 9.81); const now = Date.now(); if (delta > threshold) { exceedCount++; if (exceedCount >= minExceedCount && now - lastShakeTime > minShakeInterval) { lastShakeTime = now; exceedCount = 0; // 发送摇动事件到JS侧 } } else { exceedCount = 0; } }注意 exceedCount 在低于阈值时必须清零。否则一次摇动结束后残留计数，下次微小的加速度波动就会瞬间叠加到阈值以上，造成“连续误触”。这个细节我在早期版本里踩过，调了一整天。
另外，阈值必须暴露给上层配置。不同设备的传感器底噪水平差异很大，某些设备静止时合加速度波动能到 1.0 以上。理想做法是在原生模块里提供 setConfig 方法，或者从 JS 侧读取一个常量。硬编码阈值是鸿蒙化阶段最高的坑。
3.3 从原生侧到 JS 侧的事件推送链路
判定成功之后，原生模块要往 JS 侧发一个事件。React Native 的 DeviceEventEmitter 机制在 OpenHarmony 侧同样有对应实现，最常见做法是拿到舞台的 emitter 实例，调用 emit。
我封装时写了类似这样的逻辑：
import { deviceEventEmitter } from '@kit.ArkTS'; // 具体模块按RN兼容层暴露方式为准 function emitShakeEvent() { deviceEventEmitter.emit('shake'); }在 JS 侧，业务代码拿到的是 RN 框架自己的 DeviceEventEmitter，监听同名事件：
import { DeviceEventEmitter } from 'react-native'; const subscription = DeviceEventEmitter.addListener('shake', () => { // 触发业务逻辑 });整个推送链路的关键是“同名”和“同通道”。很多人在组件加载完成后添加监听，但是因为原生 Sensor 还没注册成功，或者监听器被 GC 回收，导致事件丢失。这里我建议在原生模块里通过一个简单地适配器设计，把 JS 侧的监听和原生模块的注册统一管理：JS 侧 addListener 时，若传感器尚未启动，则此刻启动传感器；remove 最后一个监听时再关闭传感器。这样资源管理干净，也不会出现页面还没挂载就白白耗电的问题。
4. 实操记录：鸿蒙化 react-native-shake 全流程
4.1 工程准备与依赖配置
这次改造的模拟项目我起名叫 react-native-shake-harmony，完全仿照原库的目录结构，方便后续自动链接替换。
初始目录是这样的：
react-native-shake-harmony/ ├── android/ # 原有Android实现 ├── ios/ # 原有iOS实现 ├── src/ │ └── index.ts # JS封装 ├── harmony/ │ └── src/main/ets/ │ ├── RNShakeModule.ets │ └── RNShakePackage.ets └── package.json改造的关键是 package.json。RN for OpenHarmony 的自动链接工具会扫描三方库的 harmony 字段，找到原生包入口。我在 package.json 里加了一段类似下面的配置：
{ "name": "react-native-shake-harmony", "version": "1.0.0", "harmony": { "alias": "react-native-shake", "packageName": "RNShakeHarmony", "path": "harmony" } }这里 alias 很关键。它告诉工具：虽然包名是 react-native-shake-harmony，但在 React Native 代码里仍然以 react-native-shake 作为包名来解析。这样业务代码不需要改动 import 语句。
4.2 实现原生模块代码
原生侧我写了一个 RNShakeModule，继承 RN 兼容层的 TurboModule 类。整体逻辑分三块：模块生命周期、传感器管理、摇动判定。
骨架如下：
import { TurboModule } from 'react-native-oh-turbo/ts'; // 兼容层实际导入路径以项目为准 import { sensor } from '@kit.SensorServiceKit'; export class RNShakeModule extends TurboModule { private registered = false; private lastShakeTime = 0; private exceedCount = 0; private readonly threshold = 2.5; private readonly minExceedCount = 3; private readonly minShakeInterval = 500; constructor(ctx) { super(ctx); } private onSensorDataChanged(data) { const magnitude = Math.sqrt(data.x * data.x + data.y * data.y + data.z * data.z); const delta = Math.abs(magnitude - 9.81); const now = Date.now(); if (delta > this.threshold) { this.exceedCount++; if (this.exceedCount >= this.minExceedCount && now - this.lastShakeTime > this.minShakeInterval) { this.lastShakeTime = now; this.exceedCount = 0; this.emitShake(); } } else { this.exceedCount = 0; } } private emitShake() { if (this.context) { this.context.getDeviceEventEmitter()?.emit('shake'); } } startSensor() { if (this.registered) return; sensor.on(sensor.SensorId.ACCELEROMETER, this.onSensorDataChanged, { interval: sensor.SensorInterval.GAME, }); this.registered = true; } stopSensor() { if (!this.registered) return; sensor.off(sensor.SensorId.ACCELEROMETER, this.onSensorDataChanged); this.registered = false; } }上面的 onSensorDataChanged 回调必须是稳定的函数引用，不能用匿名箭头函数直接塞给 sensor.on，否则后面 sensor.off 时无法解除监听。这是传感器相关 API 很经典的问题，顺手记一笔。
4.3 封装模块包装类并完成注册
RN 兼容层需要识别这个模块。我写了一个 RNShakePackage，在 createNativeModules 里返回实例：
import { TurboModulePackage } from 'react-native-oh-turbo/ts'; export class RNShakePackage extends TurboModulePackage { createNativeModules(ctx) { return { RNShake: new RNShakeModule(ctx), }; } }这样框架里可以通过 RNShake 这个名字拿到原生模块。与此同时，在模块的构造过程里，我通过 context 挂载了生命周期回调。推荐的做法是：当 JS 侧第一次调用注册方法时再 startSensor，而不是包加载时就启动传感器。因为很多应用启动后根本不会打开摇一摇页面，提前启动传感器等于白耗电。
为了达到这个目的，我在模块里加了一个 registerShakeListener 方法，JS 侧 addListener 时调它，remove 时调 unregisterShakeListener。没有监听者时，传感器应该完全关闭，避免后台误触发和耗电。
4.4 JS 侧封装并兼容原库 API
JS 侧的代码核心是导出一个与原库结构一致的对象。原库常见的调用形式有 Shake.addListener、Shake.addEventListener、Shake.removeAllListeners。我都做了兼容。
import { NativeModules, DeviceEventEmitter } from 'react-native'; const NativeShake = NativeModules.RNShake; const SHAKE_EVENT = 'shake'; const Shake = { addListener(type: string, handler: () => void) { if (type !== 'shake') return { remove() {} }; NativeShake?.registerShakeListener?.(); const emitterSubscription = DeviceEventEmitter.addListener(SHAKE_EVENT, handler); return { remove() { emitterSubscription.remove(); // 这里额外调用NativeShake.unregisterShakeListener，也可由移除最后一个监听时触发 NativeShake?.unregisterShakeListener?.(); }, }; }, addEventListener(type: string, handler: () => void) { return this.addListener(type, handler); }, removeAllListeners(type: string) { if (type !== 'shake') return; NativeShake?.unregisterShakeListener?.(); DeviceEventEmitter.removeAllListeners(SHAKE_EVENT); }, }; export default Shake;这里有个问题是 removeListener 和 addListener 的配对次数问题。如果业务侧反复 addListener 后 remove，原生侧的传感器打开关闭会被频繁触发。我又在原生侧加了一个计数器，只有监听数从 0 变 1 时才 startSensor，从 1 变 0 时才 stopSensor。这种计数式管理能有效避免多次注册导致传感器状态错乱。
4.5 安装、构建与真机联调
把包目录放进 RN for OpenHarmony 项目的 node_modules 后，重新 install，再执行一次原生同步命令，让自动链接工具扫描 harmony 包。构建阶段要留意编译器是否能解析到 @kit.SensorServiceKit 的依赖声明。如果项目本身的 OpenHarmony SDK 版本偏老，可能需要把传感器依赖显式写入工程的 oh-package.json5。
真机联调时我是这么验证的：
先打开应用，进入预先留好测试按钮的页面。点击按钮注册监听。然后拿起手机，做一次短促有力的甩动。观察 Log 里是否打印 "shake event". 如果没有，先确认传感器是否注册成功，再确认事件名。我用过一个笨办法，在传感器回调里加一个原始数据打印，然后对着 Log 晃动手机，看 data.x/y/z 是否有明显变化。能排除“手机没在采集”这种低级问题。
5. 常见问题与排查技巧实录
5.1 传感器事件不触发或触发异常
这是改完之后遇到最多的现象。我整理了几个高频原因：
- 传感器根本没有注册。可能是 NativeShake 为 null，JS 侧调用 registerShakeListener 时用了可选链静默失败。应该检查 NativeModules.RNShake 是否存在，如果不存在，大概率是自动链接没把原生包加进去。
- 采样间隔过长。如果不是 GAME 模式而是普通模式，传感器可能低频输出，摇动过程里只采到少量超阈值点，永远凑不够连续帧数。调到 GAME 模式后触发率明显提升。
- 回调没有稳定持有。上面提到过，如果回调函数写成匿名箭头，sensor.off 时可能解除失败，导致重复注册。
排查时我从三个方面下手：确认模块是否存在、传感器是否注册成功、数据是否真的在变化。这三步能过滤掉绝大多数“完全不触发”的问题。
5.2 误触频繁，灵敏度像“神经质”
误触的源头基本都在阈值和判定策略。真机上只是轻轻抬手、走路、甚至把手机从桌上拿起来，合加速度都会有明显尖峰。早期我把连续帧数设成 2，阈值设为 2.0，结果每次把手机从兜里拿出来都会触发摇一摇。
调整方案有三个方向：
- 提高阈值到 2.5 到 3.0 之间，具体要根据测试机特性。
- 提高连续帧数到 3 到 5 帧，让“有效摇动”必须具备一定持续时间。
- 增加方向变化的判断。真实的摇一摇是反复、往返的晃动，加速度方向会交替变化。可以在连续超阈值序列里检查是否有方向翻转，没有翻转的直接忽略。这个逻辑能有效过滤掉单次抬手的误触。
我最后选的是“阈值+帧数+方向变化”组合。虽然代码比单阈值复杂很多，但真机上的可靠率从大约 60% 提升到了 95% 以上。
5.3 事件吞吐、线程与时机问题
传感器回调是在 OpenHarmony 的系统传感器线程里执行的。如果在这个回调里做重活，比如字符串拼接、打大量 Log、直接操作 UI，会造成回调卡顿甚至丢帧。我曾经在回调里加了一行 JSON.stringify，把整个数据对象转成字符串打日志，结果肉眼可见地感觉到摇动事件变迟钝。
正确的做法是：传感器回调里只做最轻量的数学计算和状态记录，判定成功后再通过 RN 的事件通道投递。事件投递本身是异步的，JS 侧不会收到实时数据，但业务上完全够用。
还有时机问题。页面还没完成加载时，原生模块可能还没注册完，JS 侧太早调用 addListener 会导致后面监听挂空。解决方式是在 componentDidMount 或 useEffect 里注册，同时保证原生模块内部有“注册传感器失败自动重试”的补偿逻辑。不过对摇一摇来说，更常见的是用户进入页面后过几百毫秒才开始摇，所以影响不大。
5.4 与 RN 版本/API 差异兼容问题
OpenHarmony 上的 RN 兼容层还在快速演进，不同版本的 TurboModule 基类、上下文获取方式、事件发射器 API 都有差异。react-native-shake 原库在 Android 上用的 old bridge 方式，在 OpenHarmony 上我一开始参照某个新版本写法，编译过了但事件一直发不到 JS。后来查文档发现是上下文获取方式变了，换用新版 API 就好了。
兼容问题我建议在模块内部做一层薄薄的适配。比如获取事件发射器时，优先用新接口，拿不到再退回旧接口。这样当升级 RNOH 版本时，业务侧不会突然崩掉。
另外，原库中有一些旧版 RN 的方法签名，在 OpenHarmony 的兼容层里不一定齐全。ensure 所有异步方法都返回 promise 或用 callback 包装，避免原生侧直接抛异常把 JS 侧打挂。
把这么多问题解决完，再回头看 react-native-shake 的鸿蒙化，其实就是一个“翻译+重写+调参”的过程。翻译的是 API 调用，重写的是事件链路，调参的是摇动判定算法。做这种三方库改造，最有价值的不是把代码跑通，而是把原生平台差异摸透，并且沉淀出可以复用的适配模板。我在实际项目中一直保留着这套模板，后续再碰到类似传感器、定位、扫码类库的鸿蒙化改造，基本就是换壳换算法的事，踩坑成本低了很多。
