
移动开发UI组件【免费下载链接】react-native-gesture-handlerDeclarative API exposing platform native touch and gesture system to React Native.项目地址https://gitcode.com/gh_mirrors/re/react-native-gesture-handler点击查看免费下载本文以 react-native-gesture-handler 官方 2.x 版本文档《Upgrading to the new API introduced in Gesture Handler 2》为主体结合仓库中packages/react-native-gesture-handler/src的真实源码系统讲解从 1.x 组件式 API 迁移到 2.x Gesture API 的完整路径先解决 Android 上RNGestureHandlerEnabledRootView的历史包袱再掌握Gesture对象、GestureDetector组件、新回调模型onBegin/onStart/onUpdate/onChange/onEnd/onFinalize、链式配置手势以及用组合 API 替换嵌套 Handler 与waitFor/simultaneousHandlers的全部方法。读完本文你可以把旧式TapGestureHandler、PanGestureHandler等组件代码平稳改写为声明式、可组合的新 API。一、迁移前置条件先脱离RNGestureHandlerEnabledRootView仅 AndroidGesture Handler 1.x 要求通过重写createRootView返回RNGestureHandlerEnabledRootView实例才能让手势系统在 Android 上工作。该类的实现方式一直是许多难以定位、难以修复的崩溃hard-to-debug and hard-to-fix crashes的源头因此在2.0 中被标记为废弃deprecated并在2.4 中被彻底移除。如果项目里还在使用它请先完成迁移详细迁移步骤见仓库文档 migrating-off-rnghenabledroot 指南。迁移完成后Android 上不再需要任何自定义 RootView 包装GestureHandlerRootView即可承载新 API详见仓库文档 root-view.mdx 与组件实现 GestureHandlerRootView.android.tsx。只有先完成这一步升级到新 API 才有干净的基座。二、新 API 概览Gesture对象 GestureDetector组件2.x 最核心的变化是引入新的 Gesture API以及配套的GestureDetector组件。旧式 API 为每种手势单独提供组件TapGestureHandler、PanGestureHandler、PinchGestureHandler……而新 API 则通过一个GestureDetector组件把“手势配置对象”挂接到它包裹的视图上大量样板代码被库内部消化掉。配置对象由Gesture对象创建例如const tapGesture Gesture.Tap().onStart(() { console.log(Tap!); }); ... return ( GestureDetector gesture{tapGesture} View / /GestureDetector );从源码看Gesture.Tap()实际返回一个TapGesture实例见 gestureObjects.ts它继承自BaseGesture每个实例会分配唯一的gestureId并维护自己的config与handlers见 gesture.ts。GestureDetector在挂载/更新时通过 attachHandlers.ts、updateHandlers.ts 等模块把配置下发到原生侧这是“省去大量样板代码”的底层来源。提示仓库主分支源码已将Gesture构建器 API 标记为deprecated建议逐步迁移到新的 hook 式 API如useTapGesture见 gestureObjects.ts 的注释。但 2.x 版本文档所对应的升级路径依然以Gesture对象为核心且其回调与配置语义与 hook API 一致掌握本节即可平滑衔接后续演进。三、告别onGestureEvent与onHandlerStateChange新的回调模型新 API 中不再有onGestureEvent和onHandlerStateChange这两个回调。状态机由库在底层自动驱动开发者只需为“特定状态迁移或事件”注册对应回调。手势状态常量定义在 State.tsUNDETERMINED: 0, FAILED: 1, BEGAN: 2, CANCELLED: 3, ACTIVE: 4, END: 5新回调与状态迁移的对应关系如下回调触发时机onBegin手势进入BEGAN状态。大多数情况下即手指首次触碰到视图、手势开始处理触摸流的时候onStart手势满足激活条件从BEGAN迁移到ACTIVE状态onUpdate替代onGestureEvent在手势处于ACTIVE状态期间每次收到新事件时触发onChange若已定义则在onUpdate之后立即触发事件数据与onUpdate相同但额外携带change字段表示自上一个事件以来的变化量例如Pan手势会额外携带changeX、changeYonEnd手势从ACTIVE迁移到END、FAILED或CANCELLED三者之一。回调的第二个参数success用于区分手势是因用户操作完成还是因其他原因被系统取消、满足失败条件而结束onFinalize手势进入END、FAILED或CANCELLED状态时触发如果手势此前处于ACTIVE则onEnd会先被调用同样可用第二个参数判断结束原因onEnd与onFinalize的核心区别onEnd仅在手势曾处于ACTIVE状态时才调用onFinalize只要手势进入过BEGAN就会被调用。因此推荐用onEnd清理onStart中建立的资源用onFinalize清理onBegin或同时清理onBegin与onStart中建立的资源。在源码层面对应关系清晰可查BaseGesture中定义了onBegin/onStart/onEnd/onFinalize见 gesture.tsContinousBaseGesture定义了onUpdate/onChange/manualActivation见 gesture.ts。所有回调都会在注册时通过isWorklet(callback)检测是否为 Reanimated worklet并记录到handlers.isWorklet数组中——如果安装了react-native-reanimated且回调均为 worklet则默认在 UI 线程执行也可用.runOnJS(true)强制切回 JS 线程见 gesture.ts。以Pan手势为例onChange的changeX/changeY由changeEventCalculator计算首次事件取当前translationX/translationY之后取与上一次事件的差值见 panGesture.ts这就是“变化量”语义的实现来源。四、链式配置手势从 Props 到 Builder 方法新 API 采用builder 链式模式配置手势。每个手势提供与旧 Props 同名或高度相似的方法来完成定制方法调用返回手势自身可连续链式书写。旧式写法return ( TapGestureHandler numberOfTaps{2} maxDurationMs{500} maxDelayMs{500} maxDist{10} onHandlerStateChange{({ nativeEvent }) { if (nativeEvent.state State.ACTIVE) { console.log(Tap!); } }} View / /TapGestureHandler );新 API 写法效果完全相同const tapGesture Gesture.Tap() .numberOfTaps(2) .maxDuration(500) .maxDelay(500) .maxDistance(10) .onStart(() { console.log(Tap!); }); return ( GestureDetector gesture{tapGesture} View / /GestureDetector );结合 tapGesture.ts 的源码上述方法的底层配置项与默认值如下链式方法底层 config 字段默认值含义.numberOfTaps(count)numberOfTaps1激活手势所需的最少点按次数.maxDistance(maxDist)maxDist无一次点按中手指允许移动的最大距离点.maxDuration(duration)maxDurationMs500手指按下后必须在该毫秒数内抬起.maxDelay(delay)maxDelayMs500多点点按时两次点按之间允许的最大间隔毫秒.minPointers(minPointers)minPointers1激活前必须放下的最少手指数.maxDeltaX(delta)/.maxDeltaY(delta)maxDeltaX/maxDeltaY无单轴方向允许的最大位移点注意新旧方法名的差异旧 propmaxDurationMs对应方法.maxDuration(...)maxDelayMs对应.maxDelay(...)maxDist对应.maxDistance(...)。其他手势的可用修饰符可查阅仓库文档中的 Gestures 章节如 use-pan-gesture.mdx、use-tap-gesture.mdx例如Pan手势额外提供activeOffsetX/Y、failOffsetX/Y、minDistance、minVelocity、averageTouches等且activeOffsetX/Y支持传入区间数组[start, end]见 panGesture.ts。五、同一视图挂多个手势用组合 API 替代嵌套 Handler使用旧式 Handler 组件时若要在同一视图上识别多种手势只能把组件层层堆叠若要叠加动画还得在每个 Handler 之间插入Animated.View最终形成很深的组件树return ( TapGestureHandler ... Animated.View PanGestureHandler ... Animated.View PinchGestureHandler ... YourView / /PinchGestureHandler /Animated.View /PanGestureHandler /Animated.View /TapGestureHandler );使用GestureDetector后可以借助Gesture Composition API详见 gesture-composition 文档把多个手势组合到同一视图上const tapGesture Gesture.Tap(); const panGesture Gesture.Pan(); const pinchGesture Gesture.Pinch(); return ( GestureDetector gesture{Gesture.Race(tapGesture, panGesture, pinchGesture)} YourView / /GestureDetector );组合 API 提供三种基本组合对应旧式堆叠的不同语义Gesture.Race(...)ComposedGesture第一个激活的手势会取消其余手势。从源码看Race只是把各手势放进一个普通组合不额外建立同时或等待关系见 gestureObjects.ts。Gesture.Simultaneous(...)SimultaneousGesture用于替代“应当能同时识别”的堆叠 Handler。其prepare()会为每个手势构造“除自己之外的所有手势”列表并写入simultaneousWith关系且不会让手势与自己同时见 gestureComposition.ts。Gesture.Exclusive(...)ExclusiveGesture用于替代“要求其他手势失败才能识别”的堆叠 Handler。其prepare()按传入顺序建立链式requireToFail关系——越靠前的手势优先级越高后面的手势需要等待前面的手势全部失败见 gestureComposition.ts。典型例子Exclusive(doubleTap, singleTap)可同时支持双击与单击。源码细节组合手势在prepare()阶段会把关系写入各子手势的config.simultaneousWith/config.requireToFail并基于relationsSnapshot重建避免重复渲染时关系引用不断累积导致内存泄漏见 gestureComposition.ts 的注释涉及 issue #3763、#4238。六、替换waitFor与simultaneousHandlers跨视图手势关系组合 API 解决的是同一视图上多个手势的关系。如果需要建立不同视图上手势之间的关系或需要让新手势与旧式 Handler 组件建立关系则应使用以下方法simultaneousWithExternalGesture(...gestures)替代旧 propsimultaneousHandlers允许多个组件上的手势同时识别。requireExternalGestureToFail(...gestures)替代旧 propwaitFor延迟当前手势的激活直到传入的手势全部失败或根本不开始。withRef(refObject)当需要把 ref 对象传给旧式 Handler 组件用于旧 API 互操作时用.withRef(ref)把它挂到手势对象上。三者均为链式方法可一次传入多个手势见 gesture.tsconst panGesture Gesture.Pan().withRef(panRef); const pinchGesture Gesture.Pinch(); const longPressGesture Gesture.LongPress() .requireExternalGestureToFail(pinchGesture) .simultaneousWithExternalGesture(panGesture);源码确认simultaneousWithExternalGesture/requireExternalGestureToFail/blocksExternalGesture内部通过addDependency把目标手势追加进config.simultaneousWith/config.requireToFail/config.blocksHandlers数组见 gesture.ts而withRef会把 ref 写入config.ref并在手势initialize()时把ref.current指向手势实例从而与旧 API 的 ref 体系对接见 gesture.ts 与 gesture.ts。七、迁移清单与后续路径综合全文从 1.x 升级到 2.x 的完整动作可归纳为Android确认已移除RNGestureHandlerEnabledRootView详见 migrating-off-rnghenabledroot必要时用GestureHandlerRootView替代。组件 → 对象把XxxGestureHandler组件替换为Gesture.Xxx()配置对象 GestureDetector gesture{...}。回调 → 状态迁移把onGestureEvent改写为onUpdate把onHandlerStateChange中对State.ACTIVE、State.END等的手工判断改写为onStart、onEnd、onFinalize等语义化回调需要增量数据时追加onChange。嵌套 → 组合同视图多手势用Gesture.Race/Gesture.Simultaneous/Gesture.Exclusive跨视图关系用simultaneousWithExternalGesture/requireExternalGestureToFail并用withRef兼容旧 Handler ref。当前主线展望仓库主分支已将Gesture构建器、ComposedGesture等标记为弃用推荐向 hook 式 APIuseTapGesture、usePanGesture、useSimultaneousGestures等演进见 gestureObjects.ts。2.x 升级文档中的回调语义、配置字段与组合关系模型在 hook API 中保持一致可平滑迁移。相关实现与文档入口汇总手势基类与回调gesture.ts组合实现gestureComposition.ts手势工厂gestureObjects.ts状态常量State.ts组合 API 完整文档gesture-composition.md官方测试用例验证GestureDetector组合行为api_v3.test.tsx、RelationsTraversal.test.tsx赞分享移动开发UI组件【免费下载链接】react-native-gesture-handlerDeclarative API exposing platform native touch and gesture system to React Native.项目地址https://gitcode.com/gh_mirrors/re/react-native-gesture-handler点击查看免费下载相关推荐React Native Gesture Handler 3 迁移实战从 Builder API 平滑升级到 Hook APIReact Native Gesture Handler 3 迁移实战从 Builder API 平滑升级到 Hook API 本指南以 react nati移动开发UI组件react-native-gesture-handler 的 Gesture 对象手势创建、组合与 v3 Hook API 迁移指南react native gesture handler 的 Gesture 对象手势创建、组合与 v3 Hook API 迁移指南 Gesture 是 re移动开发UI组件react-native-gesture-handler GestureDetector 组件完全指南手势创建、更新与组合原理react native gesture handler GestureDetector 组件完全指南手势创建、更新与组合原理 GestureDetector移动开发UI组件上一篇Apache DolphinScheduler 全面解析分布式可视化 DAG 工作流调度平台入门指南下一篇mGBA模拟器完全指南从新手到高手的7个实用技巧创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考