React Native 鸿蒙智感握姿实战:把系统握感事件翻译成跨平台状态模型
原生订阅怎么接、未知状态码怎么兜底、Android 和 iOS 没有这个能力时三端怎么共享一套模型——这篇文章用一个封装"智感握姿"的 RN 三方库,把这三个问题一次讲透。
仓库地址:https://atomgit.com/oh-react-native/react-native-smart-grip
版本地址:https://atomgit.com/oh-react-native/ohos_react_native
三方库框架:https://atomgit.com/oh-react-native
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 打开 harmony/ 或 example/ohosApp 即可构建(Stage 工程,compatibleSdkVersion 6.0.0(20) / targetSdkVersion 6.0.0(20)) |
| React Native | 示例工程 0.72.5(库 peer >= 0.70,RN 0.60+ 自动链接) |
| RNOH | @rnoh/react-native-openharmony 0.72.146(example/ohosApp 宿主同版本) |
| react-native-smart-grip | 0.1.0(本仓库,Apache-2.0) |
| 系统能力 | SystemCapability.MultimodalAwareness.Motion(motion.on('holdingHandChanged')) |
| 权限 | ohos.permission.DETECT_GESTURE + ACTIVITY_MOTION(in-use,由宿主声明) |
| 自检 | npm run selfcheck:TypeScript 编译 + 引擎六项不变量 + KMP 对齐断言(Node 环境,无需真机) |
| 实测设备 | HUAWEI ALN-AL00,HarmonyOS 7.0.0.109(API 26) |
1. 系统握感事件从哪来
起因很简单。产品想要一个"单手模式":检测到用户左手握持时把操作区挪到左侧,右手握持挪到右侧,双手握持进入大屏模式。我最初的想法很直接:RN 里监听个系统事件,addListener 一挂就完事。动手才发现三件事都没有现成答案:
第一,事件在原生层。 鸿蒙的握姿感知位于多模态感知 Kit 里——motion.on('holdingHandChanged') 是 ArkTS 侧的 API,JS 层访问不到;要在 RN 里用它,得走 RNOH 的 TurboModule 接入,而且 RNOH 的一个特性差点让我卡住:仅有 ArkTS Package 时,JS 拿不到方法——还必须在 C++ 侧提供 TurboModule 方法表声明(第 6 节细说)。
第二,能力是鸿蒙独有的。 Android 的公开 SDK 没有对应 API,iOS 也没有。可这个功能的产品定义是跨端的——单手模式在三个平台都要有。直接放弃非鸿蒙端?不行;各端各写一套状态逻辑?以后左手是 1 还是"LEFT"都说不齐。
第三,状态码由系统定义。 系统回调给的是一个裸数字,未来 SDK 新增状态码怎么办?用户手里的旧设备返回不认识的码怎么办?
多模态感知 Kit 的文档里,握姿相关的就一个 holdingHandChanged 事件和一个 HoldingHandStatus 类型,四个取值,没有时间戳、没有置信度、没有事件序号。翻自己之前的工程时才想起来,kmp-smart-grip 那套状态模型当初就是为"系统只给裸数字"的场景设计的——模型是现成的,缺的只是 RN 这条原生通路。
所以这个题目的边界很清楚:从 KMP 工程 kmp-smart-grip 移植一套纯 JS 状态模型,鸿蒙侧订阅系统事件并归一化成快照,Android/iOS 侧保留模型与挂钩点。具体拆成三件事:
- 原生订阅怎么接(TurboModule、能力探测、幂等生命周期);
- 归一化快照与状态模型(UNKNOWN 兜底、sequence 单调、与 KMP 一致的 JSON 线格式);
- 三端兼容(Android/iOS 的厂商挂钩点、RNOH 的 Platform.OS 回退)。
2. 效果展示
示例应用标题直接写了架构:智感握姿 · react-native-smart-grip · OpenHarmony 多模态感知 + 跨平台状态模型。页面从上到下四块:平台支持检测、当前握持状态、事件日志、引擎演示。
真机上左手握起手机,第一张截图的状态卡实时跳变:

平台支持检测显示"✅ 当前平台支持"——注意下面一行 Platform: android,这不是判错了,是 RNOH 的特征:Platform.OS 在鸿蒙宿主上仍回退为 android(第 6 节细说)。状态卡大字"左手握持",下面是机器可读的三元组:状态码 1 · LEFT,事件序号 1。事件日志(最多保留 20 条)里,01:09:42 的"真机事件:左手握持(code=1,sequence=1)"就是系统 holdingHandChanged 回调穿过 TurboModule 到达 JS 的完整记录。
换成右手,状态卡跟着换:

“右手握持 · 状态码 2 · RIGHT · 事件序号 2”。日志往下翻能看到完整的轨迹:01:09:40 右手(sequence=0)→ 01:09:42 左手(sequence=1)→ 01:09:46 右手(sequence=2)。sequence 从 0 开始、每次事件 +1、跨左右手切换连续递增——这是原生侧维护的单调计数,两次订阅周期之间也不清零。
双手同握,三个状态凑齐:

“双手握持 · 状态码 3 · BOTH · 事件序号 3”,日志里 0 → 1 → 2 → 3 四个事件单调递增。最下方的"引擎演示(本地快照,与真机事件解耦)"是独立的一块:它用 SmartGripEngine.reduce 在本地推进快照,模拟全部 5 个文档化状态——与真机事件完全解耦,任何平台都能演示,Android 和 iOS 上就是靠它体验状态模型的。
三段截图之外,还有两个真机上的观察,先记下来。一是手机平放在桌上不会有任何事件,拿起手机时才出第一条——所以日志里 sequence=0 多半是"拿起手机的那只手",不是噪声;二是换手不瞬时,系统内部有自己的防抖,实际感受是一两秒之后状态卡才跳。握姿是状态而不是触摸事件,做 UI 时不能按触摸事件的频率来预期它。
3. 事件、快照与不变量:模型输入从哪来
写代码之前得先把原理捋好。
整条链路是"订阅 → 归一化 → 分发"三级:
系统(多模态感知 Kit)
motion.on('holdingHandChanged') ← ArkTS TurboModule 订阅
│ HoldingHandStatus → Number(code),非整数归 UNKNOWN(16)
▼
SmartGripTurboModule(RNOH 原生,sequence 单调计数,跨 start/stop 周期)
│ DeviceEventEmitter:'smartGripHoldingHandChanged',payload { code, sequence }
▼
JS 门面 SmartGrip.snapshotFromPayload
│ code 非整数 → UNKNOWN;sequence 无效 → JS 本地兜底计数
│ SmartGripEngine.snapshot → 不可变快照
▼
业务 listeners(addHoldingHandListener,返回 {remove()})
└─ Android / iOS:没有系统事件,但 SmartGripEngine 状态模型完全同款
先看系统到底给了什么。原生侧能拿到的全部家当,就是这样一个回调:
import { motion } from '@kit.MultimodalAwarenessKit';
motion.on('holdingHandChanged', (status: motion.HoldingHandStatus) => {
// HoldingHandStatus:0 未握持 / 1 左手 / 2 右手 / 3 双手
});
一个事件,一个数字,再无其他——没有时间戳,没有置信度,没有序号。这也解释了链路图里 sequence 为什么要原生侧自己维护:系统不提供序号,桥这一层要自己维护。
归一化的原则是"不信任透传"。 系统回调的裸数字直接透传到业务层,等于把系统 SDK 的版本差异泄漏给每一个业务调用点:未来 SDK 新增了状态码 4,业务里 switch (code) 就会进入未定义分支。所以库在两级各做一次防御——原生侧把非整数码归一到 UNKNOWN(16),JS 门面再兜一次底;UNKNOWN 表示系统返回了库不认识的状态,中文显示名是"未识别"。
sequence 用来区分事件。 同一个状态(比如连续两次右手)产生的事件字段完全相同,业务没法区分"是新事件还是重复推送";原生侧的单调计数让每个事件有唯一序号,且跨 start/stop 订阅周期连续——restart 不会让序号倒挂。
JSON 线格式与 KMP 逐字段一致。 snapshotToJson 产出 {"code":1,"status":"LEFT","displayName":"左手握持","sequence":1},字段顺序、转义规则与 KMP 的 toJson() 线格式对齐——这是从 kmp-smart-grip 移植时的硬承诺,自检脚本里逐项断言。
性能开销也记一笔:握姿事件是低频状态变化,不是传感器流——单手模式每秒最多切换几次,TurboModule 的事件分发和 JS 侧快照构造都在微秒级,主线程压力很小;归约器只做内存运算,无网络、无高频采样。瓶颈不在事件链路,在业务侧拿握姿状态做什么。
各条路线对照一下:
| 接入方式 | 三端一致性 | 说明 |
|---|---|---|
| 各端各写原生订阅 | 无 | Android/iOS 没有对应系统 API,无从写起 |
| 传感器原始数据自研手势识别 | 无 | 算法门槛高,且与系统握姿语义不一致 |
| 仅鸿蒙 ArkTS 页面直接用 Kit | 单端 | 放弃 RN 跨端,业务代码分叉 |
| KMP 版 kmp-smart-grip | 双端 | Kotlin 引擎,RN 无法直接消费 |
| 本库 | 三端共享状态模型 | OpenHarmony 完整能力;Android/iOS 保留模型 + 厂商挂钩点 |
能力边界照 仓库说明的兼容矩阵说清楚:OpenHarmony/HarmonyOS 是完整能力(RNOH 原生模块实时分发归一化快照);Android 与 iOS 是仅共享状态模型——无原生实现,isSupported() 返回 false,但 SmartGripEngine 的全部语义(快照、归约、自检、JSON)在任意平台可用。理解这个边界之后,单手模式在非鸿蒙端要么走厂商挂钩点,要么用引擎演示做降级体验;库不会把 isSupported() 报成 true。
4. 工程怎么搭:一个纯 JS 模型,三个平台壳
先看整体结构。从 KMP 移植来的库,目录结构与架构对应——src/ 是纯 JS/TS 的模型层(零平台依赖),三个平台目录各是一个"壳":
react-native-smart-grip/
├─ src/ # 纯 JS/TS:状态枚举、快照、归约器、JSON 边界、门面
│ ├─ SmartGripStatus.ts # 枚举 NONE=0/LEFT=1/RIGHT=2/BOTH=3/UNKNOWN=16
│ ├─ SmartGripSnapshot.ts # 不可变快照
│ ├─ SmartGripEngine.ts # snapshot / reduce / catalog / runChecks
│ ├─ SmartGripJson.ts # JSON 线格式(与 KMP 一致)
│ ├─ SmartGripModule.ts # 业务门面(订阅生命周期 + 事件分发)
│ ├─ NativeSmartGrip.ts # 原生模块规格
│ └─ index.ts
├─ harmony/ # RNOH 原生侧库工程(DevEco 可直接打开)
│ └─ smart_grip/
│ └─ src/main/ets/ # SmartGripTurboModule.ets / SmartGripPackage.ets
├─ android/ # SmartGripModule.kt(厂商/定制 ROM 挂钩点)
├─ ios/ # SmartGrip.h/m(挂钩点 stub,含 podspec)
├─ example/ # RN 0.72.5 应用 + ohosApp 鸿蒙 RNOH 完整宿主
├─ scripts/self-check.ts # Node 自检(镜像 KMP 的 JVM 测试)
├─ docs/API.md # 中文 API 文档
└─ react-native-smart-grip.podspec / tsconfig*.json

这次设计有三个决定:
状态模型是纯 JS,src/ 里没有一行平台分支。 枚举、快照、归约器、JSON 边界全部是平台无关的 TypeScript——Android 和 iOS 侧只保留最小实现,模型语义也和鸿蒙端逐字一致(枚举注释原话:“Mirrors the KMP enum … so the same codes can be shared across OpenHarmony, Android and iOS hosts”)。
Android/iOS 保留挂钩点。 SmartGripModule.kt 的类注释把定位讲得很清楚:标准 AOSP 没有对应 API,模块固定 isSupported() == false,但"定制 ROM 可继承本类,覆写 isSupported / startListening,接入自有传感器后通过 sendEvent 上报 {code, sequence},JS 层无需任何改动"。事件契约(事件名、payload、码表、序号规则)写进类注释并要求与 src/NativeSmartGrip.ts 保持同步——挂钩点接进来,三端消费代码不变。
鸿蒙侧交付"库 + 完整宿主"两件套。 harmony/smart_grip 是可直接用 DevEco 打开的 HAR 工程;example/ohosApp 是可直接运行的完整 RNOH 宿主——权限声明、Package 注册、C++ 方法表、预打包的 bundle.harmony.js 全都配好。接库的人可以直接对照完整宿主配置,不需要只按 仓库说明自己拼。
对使用方来说,JS 侧的 API 是这样的:
import {
SmartGrip,
SmartGripEngine,
snapshotDisplayName,
snapshotToJson,
} from 'react-native-smart-grip';
// 1. 监听真机事件
const supported = await SmartGrip.isSupported();
if (supported) {
await SmartGrip.startListening();
}
const subscription = SmartGrip.addHoldingHandListener(snapshot => {
console.log(snapshotDisplayName(snapshot), snapshot.sequence); // 左手握持 3
});
// 时机合适时:subscription.remove(); await SmartGrip.stopListening();
// 2. 引擎:纯本地状态模型,不依赖真机
const initial = SmartGripEngine.snapshot(0); // {status: NONE, sequence: 0}
const next = SmartGripEngine.reduce(initial, 1); // 推进到左手,sequence + 1
console.log(snapshotToJson(next));
// {"code":1,"status":"LEFT","displayName":"左手握持","sequence":1}
console.log(SmartGripEngine.runChecks()); // 六项自检
5. 把代码讲透
5.1 TurboModule:能力探测、幂等生命周期,与一次失败的回滚
SmartGripTurboModule 是事件链路的原生端点,startListening 把防御写成了三段:
// harmony/smart_grip/src/main/ets/SmartGripTurboModule.ets(节选)
startListening(): Promise<void> {
return new Promise<void>((resolve, reject) => {
if (this.callback !== null) {
resolve(); // 幂等:已在订阅中
return;
}
if (!this.isSystemCapabilityAvailable()) {
reject(this.makeUnsupportedError(
`System capability ${SYSTEM_CAPABILITY} is not available on this device`));
return; // 设备不支持:E_UNSUPPORTED
}
this.callback = (data: motion.HoldingHandStatus): void => {
const code = Number(data);
listener(Number.isInteger(code) ? code : UNKNOWN_CODE); // 归一化
};
try {
motion.on('holdingHandChanged', this.callback);
resolve();
} catch (err) {
this.callback = null; // 订阅失败:回滚状态
this.listener = null;
reject(this.makeUnsupportedError(/* ... */));
}
});
}
三个值得抄的细节:幂等——startListening / stopListening 都可重复调用,stop 在未订阅时静默成功、永不 reject(门面层的 stopListening 同样如此,原生模块缺失也安全);能力探测的两级兜底——canIUse(SystemCapability.MultimodalAwareness.Motion) 先探,但类注释写明"canIUse 本身不可用时返回 true,startListening 的运行时错误路径才是权威兜底"——探测 API 自己缺席时,宁可让真实订阅去试,也不武断报不支持;失败回滚——motion.on 抛错时把 callback / listener 置回 null,半订阅状态不会残留到下一次。最后还有 __onDestroy__:RN 实例销毁时自动释放系统订阅,漏了它就是给系统事件总线留一个孤儿监听。
顺手把 C++ 侧的注册也贴出来。TurboModule 的 ArkTS 实现之外,宿主还得在 C++ 里登记一次,两层缺一不可(具体怎么坑人,见第 6 节坑一):
// example/ohosApp/entry/src/main/cpp/PackageProvider.cpp(节选)
#include "RNOH/PackageProvider.h"
#include "SmartGripPackage.h" // harmony/smart_grip 提供的 ArkTS Package
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
return {
std::make_shared<SmartGripPackage>(ctx), // 少了这行,JS 侧永远 isSupported() == false
};
}
ArkTS 的 Package 负责实现,C++ 的 PackageProvider 负责让 RNOH 知道这个实现存在。哪层少了都不报错,只是安静地拿不到方法——这种不报错的失败最磨人,接完先跑一遍 isSupported() 再写业务,别问我是怎么知道的。
5.2 归一化:两级防御,不信任任何裸数字
JS 门面收到事件 payload 后,先过一道归一化再变成快照:
// src/SmartGripModule.ts(节选)
let fallbackSequence = 0;
function snapshotFromPayload(payload: SmartGripEventPayload): SmartGripSnapshot {
const code = Number(payload?.code);
const safeCode = Number.isInteger(code) ? code : SmartGripStatus.UNKNOWN;
let sequence = Number(payload?.sequence);
if (!Number.isInteger(sequence) || sequence < 0) {
sequence = ++fallbackSequence; // JS 侧兜底计数
}
return SmartGripEngine.snapshot(safeCode, sequence);
}
两级防御各有分工:原生侧把非整数码归到 UNKNOWN(hilog 里留下原始值,排查有据);JS 侧再兜一次——如果某个平台的原生壳没按契约给序号(漏字段、负数、非整数),门面用本地 fallbackSequence 补一个,保证业务看到的快照永远满足"sequence 非负整数"的模型约束。桥两端对同一份数据各做一次防御,这是跨语言事件链路的通用做法:契约写得再清楚,也不能假设对面永远遵守。
5.3 状态模型与 JSON 线格式:从 KMP 逐字搬来的承诺
SmartGripStatus 枚举五个值——NONE=0 / LEFT=1 / RIGHT=2 / BOTH=3 / UNKNOWN=16,每个值带中文显示名(未握持 / 左手握持 / 右手握持 / 双手握持 / 未识别),枚举注释写明它镜像 KMP 的 SmartGripStatus,“the same codes can be shared” 三端。snapshotToJson 是移植时的硬承诺:
// src/SmartGripJson.ts(节选)
export function snapshotToJson(snapshot: SmartGripSnapshot): string {
// `SmartGripStatus[value]` 取回枚举键名,等价于 KMP 枚举的 `name`。
const statusName = SmartGripStatus[snapshot.status];
return (
`{"code":${snapshotCode(snapshot)},"status":${jsonQuote(statusName)},` +
`"displayName":${jsonQuote(snapshotDisplayName(snapshot))},"sequence":${snapshot.sequence}}`
);
}
字段顺序固定为 code / status / displayName / sequence,status 用枚举键名("LEFT",对应 KMP 枚举的 name),displayName 是中文,字符串走自写的 jsonQuote 转义表("、\、\n、\r、\t、其余控制字符 \uXXXX)——和之前几篇的 JSON 契约同一套纪律:跨端线格式逐字节可对账,靠的是手写而不是 JSON.stringify 的实现细节。
5.4 归约器与六项自检:不变量是移植的验收标准
SmartGripEngine.reduce 只有三行,却藏着两条不变量:
reduce(previous: SmartGripSnapshot, code: number): SmartGripSnapshot {
if (previous.sequence >= Number.MAX_SAFE_INTEGER) {
throw new Error('Sequence overflow'); // 单调计数有上限,到顶就抛
}
return SmartGripEngine.snapshot(code, previous.sequence + 1);
}
sequence 单调 +1;到 MAX_SAFE_INTEGER 时抛错而不是绕回——序号绕回会让去重逻辑把新事件当旧事件丢掉,抛错至少让问题暴露在开发期。runChecks() 把与 KMP 共享的六项不变量写成可执行断言:五个文档化状态齐全、状态码唯一、1 → LEFT 映射正确、未知码安全兜底到 UNKNOWN、reducer 推进序号、快照暴露规范状态码。npm run selfcheck 在 Node 环境跑(先 tsc 编译再执行,镜像 KMP 的 JVM 测试)——移植是否忠实,不看注释看断言。
跑起来是这样的:
$ npm run selfcheck
六项不变量:全部通过
状态齐全(5) / 状态码唯一 / 1→LEFT / 999→UNKNOWN / reduce 序号推进 / 快照码规范
JSON 线格式:与 KMP 逐字段一致
移植完我没急着上真机,先跑这个——三秒钟出结果,比装一次包快多了,模型层的低级问题在这里暴露最划算。
5.5 Android/iOS 挂钩点:不支持时的接入方式
Android 壳在接口上留了接入点。SmartGripModule.kt 固定 isSupported() 返回 false、startListening() 以 E_UNSUPPORTED 拒绝,同时保留了一个可覆写的挂钩点:类注释把接入步骤写给厂商 ROM 的开发者——继承本类、覆写 isSupported / startListening、接入自有传感器后通过 sendEvent 上报 {code, sequence},并且把事件契约全文写进注释(事件名 smartGripHoldingHandChanged、码表 0/1/2/3/16、序号从 0 开始单调递增)。iOS 同理:SmartGrip.h/m stub 加 podspec,契约一致。这样处理后,"平台不支持"被表达成一个可覆写的钩子——厂商接入后,JS 层一行不改,三端消费代码归一。
6. 我踩过的坑(每一条都有真实出处)
这一节的坑全部来自这次开发的真实排查与代码注释记录。
坑一:ArkTS Package 注册了,JS 拿不到方法。 RNOH 接入最反直觉的一条:只注册 ArkTS 的 SmartGripPackage,SmartGrip.isSupported() 依然返回 false——RNOH 的 TurboModuleProvider 还需要 C++ 侧的方法表声明。修复:在宿主 entry/src/main/cpp/PackageProvider.cpp 提供 SmartGrip 的 C++ ArkTSTurboModule 方法表(example/ohosApp 里有完整示例),并让 PackageProvider::getPackages 返回对应 Package。教训:RNOH 的"接上"分两层,ArkTS 和 C++ 缺一不可。
坑二:权限只写在了库里,宿主没声明。 库本身作为 HAR 不声明权限,DETECT_GESTURE 和 ACTIVITY_MOTION(in-use)必须在宿主 entry 的 module.json5 里声明——漏了之后 motion.on 直接走能力不可用分支。另外 in-use 权限首次使用需按系统提示确认授权,权限被拒或设备不支持时 startListening() 以 E_UNSUPPORTED 拒绝——示例把它翻译成中文提示:"当前设备或系统不支持智感握姿感知(E_UNSUPPORTED)。"教训:库不声明权限是刻意设计,宿主的权限清单要对着文档逐条核。
坑三:Platform.OS 在 RNOH 上回退为 android。 业务里用 Platform.OS === 'ios' 区分平台,在鸿蒙宿主上永远判不进任何分支——RNOH 让 Platform.OS 仍为 android。示例的处理(App.tsx 注释):原生 SmartGrip 可用时给用户显示真实宿主 harmony (RNOH; Platform.OS 回退为 android)。教训:RN 的平台常量在 RNOH 上不可信,能力探测用 isSupported(),别用平台名。
坑四:canIUse 探测本身缺席,误报"设备不支持"。 能力探测依赖 canIUse,但某些环境下 canIUse 自己不可用——直接返回 false 就把可用的设备误杀了。修复:canIUse 不可用时 isSupported() 返回 true,由 startListening 的运行时错误路径判断(最终兜底)。探测函数自己也可能缺席,两级兜底是标配。
坑五:未知状态码透传,业务分支漏了。 系统回调给一个文档之外的码(比如未来 SDK 新增),直接 switch 的业务会进入未定义分支。修复:两级归一化——原生侧非整数归 UNKNOWN(16),枚举的 smartGripStatusFromCode default 分支兜底,runChecks 里专门断言 999 → UNKNOWN。系统的码表不受库控制,兜底必须自己做。
坑六:序号倒挂。 原生侧有单调计数,但 payload 万一缺字段或给负数,业务侧的去重逻辑会把新事件当旧事件丢掉。修复:JS 门面加本地 fallbackSequence 兜底计数(见 5.2),同时归约器在 MAX_SAFE_INTEGER 处抛 Sequence overflow 而不是绕回——序号绕回是比崩溃更隐蔽的错误:它让重复被当成新事件,让新事件被当成重复。
坑七:引擎演示与真机事件混在一起。 示例最初把引擎演示的本地快照和真机事件打进同一条日志,结果演示按钮一点,日志里真假事件分不清。修复:演示区独立成卡(“本地快照,与真机事件解耦”),任何平台都能演示但绝不污染真机事件日志。演示数据和生产数据要分开,带模拟功能的工具都应该这样处理。
坑八:以为系统没下发事件,其实是日志看错了地方。 第一次上真机联调,我盯着 Metro 的 console 等事件,握了半天手机一条日志没有,第一反应是订阅挂错了,把 TurboModule 翻来覆去看了三遍。后来才想起 5.2 节说过原生侧在 hilog 里留了原始值——DevEco 的 Log 窗口按 tag 一过滤就能看到完整事件,RN 侧的 console 在真机上没有输出。事件没到和日志没看见是两回事,这次之后我排查这类问题只用一条规则:
hdc shell hilog | grep -iE "SmartGrip|holdingHand"
11-12 01:09:42.318 4831 5197 I C01805/SmartGrip: holdingHandChanged raw=1 -> code=1, sequence=1
教训:跨语言链路里,桥哪一端打的日志就去哪一端看;console 在真机上不可信,要看 hilog。
7. 业务侧怎么消费:把第 1 节说的单手模式做完
库的交付物是快照,产品要的是界面挪动,中间这段得业务自己写。这里补一个最小可用的单手模式,顺便也算对这套状态模型的一次验收。先交代结论性的写法:状态用 useState 存,防抖靠 sequence 而不是时间窗,页面卸载时把订阅和监听一起收走。
// useHoldingHand.ts —— 按本文场景写的业务参考实现
import { useEffect, useRef, useState } from 'react';
import { SmartGrip, SmartGripStatus } from 'react-native-smart-grip';
export function useHoldingHand() {
const [status, setStatus] = useState(SmartGripStatus.NONE);
const lastSeq = useRef(-1);
useEffect(() => {
let sub: { remove(): void } | undefined;
let alive = true;
(async () => {
if (!(await SmartGrip.isSupported())) return; // 非鸿蒙端:不挂,静默降级
await SmartGrip.startListening();
if (!alive) { // 等待期间页面已经卸载
await SmartGrip.stopListening();
return;
}
sub = SmartGrip.addHoldingHandListener(s => {
if (s.sequence <= lastSeq.current) return; // 旧事件、重复事件不进状态
lastSeq.current = s.sequence;
setStatus(s.status);
});
})();
return () => {
alive = false;
sub?.remove();
SmartGrip.stopListening(); // 库是幂等的,未订阅时调用也安全
};
}, []);
return status;
}
三个决定各有各的理由。防抖用序号不用时间窗——握姿是低频状态变化,两次事件间隔几百毫秒到几秒都正常,时间窗纯属伪需求;真正要防的是同一条事件被分发两次,sequence 单调这条模型约束正好拿来当闸门。isSupported() 为 false 就直接不挂——Android 和 iOS 上这个 hook 永远返回 NONE,界面停在中间,降级不是报错。等待期间页面卸载要补一个 stop——isSupported 和 startListening 都是异步的,用户手快直接退出页面时订阅可能刚刚挂上,没有 alive 这个标记就漏掉一次监听。
消费侧就简单了:
const grip = useHoldingHand();
const shift =
grip === SmartGripStatus.LEFT ? -72 :
grip === SmartGripStatus.RIGHT ? 72 : 0; // NONE / BOTH / UNKNOWN 都回正
只有明确的左、右才挪操作区,未握持、双手、未识别一律回正——UNKNOWN 不该参与布局,“系统说了一个我不认识的状态"不等于"用户想让界面挪走”。挪动距离 72 和动画时长 180ms 都是试出来的:72 大概是拇指自然够到屏幕中带的位移,180ms 比 300ms 跟手,再快又显得跳。这两个数没什么理论依据,换成项目自己的设计规范即可。
写完这段业务代码再回头看第 3 节的三级链路:序号校验用的是原生侧的单调计数,UNKNOWN 的处理来自归一化的语义,幂等的 stop 让卸载逻辑可以重复调用。业务代码的规模也能说明模型是否够用。
8. 现在怎么用:从 npm install 到三端一个模型
经过上面的整理,这个工程是"鸿蒙完整能力 + 三端共享模型"双形态交付(npm 包名 react-native-smart-grip,版本 0.1.0,Apache-2.0)。安装:
npm install react-native-smart-grip
# 或 yarn add react-native-smart-grip
RN >= 0.60(含 0.73)自动链接,无需额外配置;RNOH 工程还需五步(详见 宿主接入说明):
- 把库的
harmony/smart_grip引入宿主 harmony 目录,entry 的oh-package.json5以路径依赖声明; createRNPackages中注册SmartGripPackage,EntryAbility继承 RNOH 的RNAbility;PackageProvider.cpp提供 SmartGrip 的 C++ 方法表(仅有 ArkTS Package 时 JS 拿不到方法);- entry 的
module.json5声明DETECT_GESTURE与ACTIVITY_MOTION(in-use)权限; - 事件契约固定为
smartGripHoldingHandChanged(payload{code, sequence}),两端保持一致。
懒得拼装的,直接用 example/ohosApp——DevEco Stage 工程,权限、注册、C++ 方法表、预打包 bundle 全配好,构建安装后就是本文截图的演示页。不上真机也能验证模型语义:
npm run selfcheck
TypeScript 编译 + 六项不变量自检,逐项校验状态码映射(1 → LEFT、999 → UNKNOWN)、JSON 线格式、sequence 单调与溢出拒绝——全部与 KMP 一致,Node 环境即可运行。更完整的 API 说明在API 文档。
往后我大概还会做两件事:一是盯系统的新状态码——哪天 SDK 真发了 4,归一化会把它兜进 UNKNOWN,库不用发版,但 仓库说明的码表得跟着更新;二是把第 7 节那个 hook 打磨一下,单独出一个 hooks 包,业务侧连那二十行都不用写。都不急,低频事件的库,模型稳了之后没什么可折腾的。
当前版本在 RN 0.72.5 示例 / RNOH 0.72.146 宿主(compatibleSdkVersion 6.0.0(20))环境下验证:自检六项不变量全过、与 KMP 的 JSON 线格式逐字段一致;鸿蒙真机三段实拍——左手握持(code=1, sequence=1)、右手握持(code=2, sequence=2)、双手握持(code=3, sequence=3),事件日志 0 → 1 → 2 → 3 单调递增,状态卡与日志实时同步;Android / iOS 宿主上 isSupported() 如实返回 false,引擎演示区在无原生能力的情况下完整推进 5 个文档化状态。系统事件来自鸿蒙,状态模型由三端共享——这个库做的是两者之间的转换。
更多推荐

所有评论(0)