【鸿蒙优选三方库】@react-native-ohos/react-native-gesture-handler：原生级手势识别与处理框架

RN 鸿蒙应用里的手势总是不跟手、和滚动冲突？@react-native-ohos/react-native-gesture-handler 基于 software-mansion 原库适配，在原生层处理手势识别，告别 JS 线程手势延迟。

包名：@react-native-ohos/react-native-gesture-handler
当前版本：v2.30.1
协议：MIT
安装：npm install @react-native-ohos/react-native-gesture-handler
仓库：https://gitcode.com/CPF-RN/rntpc_react-native-gesture-handler

一、它解决了什么问题？

React Native 自带的 PanResponder 和 Touchable 系列组件在 JS 线程处理手势，存在两个致命问题：

延迟：手势事件从原生层发到 JS 线程再返回，中间隔了 Bridge/JSI，复杂手势"不跟手"
冲突：手势和 ScrollView 滚动经常打架，拖拽一个元素结果整个列表跟着滚

react-native-gesture-handler 把手势识别下沉到原生层 ，在原生线程完成识别和状态机管理，JS 只接收最终结果------延迟更低、与滚动等原生组件零冲突。

二、核心特点

特性	说明
原生层识别	手势在原生线程处理，不经过 JS Bridge，零延迟
丰富手势类型	Tap / LongPress / Pan / Pinch / Rotation / Fling / Hover
手势组合	`Gesture.Exclusive`（互斥）/ `Gesture.Simultaneous`（同时）/ `Gesture.Race`（竞速）
原生组件兼容	与 ScrollView / FlatList / WebView 等原生组件零冲突
手势状态机	UNDETERMINED → BEGAN → ACTIVE → END/CANCEL 完整状态流转
动画联动	与 react-native-reanimated 深度集成，手势驱动动画

三、适用场景

卡片滑动交互：Tinder 式左右滑卡片。
图片缩放/旋转：双指捏合缩放、旋转手势。
侧滑菜单：左滑/右滑打开抽屉。
绘画/签名：拖拽轨迹绘制。
复杂多手势：同时拖拽 + 缩放（如地图操作）。
手势与动画联动：手势驱动 Reanimated 动画值。

四、快速上手

1. 安装

bash 复制代码

npm install @react-native-ohos/react-native-gesture-handler

在 App 入口包裹 GestureHandlerRootView：

tsx 复制代码

import { GestureHandlerRootView } from '@react-native-ohos/react-native-gesture-handler'

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      {/* 你的应用 */}
    </GestureHandlerRootView>
  )
}

2. 点击手势

tsx 复制代码

import { GestureDetector, Gesture } from '@react-native-ohos/react-native-gesture-handler'

const singleTap = Gesture.Tap()
  .onEnd(() => console.log('单击'))
  .onFinalize(() => console.log('手势结束'))

const doubleTap = Gesture.Tap()
  .numberOfTaps(2)
  .onEnd(() => console.log('双击'))

const composed = Gesture.Exclusive(doubleTap, singleTap) // 互斥：优先双击

<GestureDetector gesture={composed}>
  <View style={{ width: 200, height: 200, backgroundColor: '#4ECDC4' }} />
</GestureDetector>

3. 拖拽手势

tsx 复制代码

const pan = Gesture.Pan()
  .onUpdate((e) => {
    // e.translationX / e.translationY：相对起始位置的偏移
    translateX.value = e.translationX
    translateY.value = e.translationY
  })
  .onEnd(() => {
    // 手指抬起后回弹
    translateX.value = 0
    translateY.value = 0
  })

4. 捏合缩放

tsx 复制代码

const pinch = Gesture.Pinch()
  .onUpdate((e) => {
    scale.value = e.scale // 当前缩放比例
  })

五、亮点能力速览

手势组合 ：Exclusive（互斥）/ Simultaneous（同时识别）/ Race（先到先得），满足复杂交互
原生线程执行 ：runOnJS(false) 让回调在原生线程跑，配合 Reanimated 实现 60fps 手势动画
与 ScrollView 共存 ：activeOffsetX / failOffsetX 精确控制手势激活条件，不误触滚动
完整生命周期 ：onBegin → onStart → onUpdate → onEnd → onFinalize

六、版本演进

版本	RN 版本	说明
2.30.1	0.82	最新版
2.23.2	0.77	兼容 0.77
2.14.18	0.72	兼容 0.72，支持 Autolink

七、为什么值得选它？

原生级性能：手势识别在原生线程，不走 JS Bridge，延迟最低。
手势丰富：Tap/Pan/Pinch/Rotation/Fling/LongPress 全覆盖。
组合灵活：互斥/同时/竞速三种组合模式，复杂交互一把梭。
生态核心：react-navigation、react-native-reanimated 都依赖它。
API 一致：与 iOS/Android 完全一致，跨平台零改动。

如果你的 RN 鸿蒙应用有任何"非按钮"的交互需求------@react-native-ohos/react-native-gesture-handler 是基础设施级别的必选项。