移动开发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中的Gesture对象展开它是新版声明式手势 API 的入口通过Gesture.Tap()、Gesture.Pan()等工厂方法创建手势实例再交给GestureDetector绑定到视图并通过Gesture.Race()、Gesture.Simultaneous()、Gesture.Exclusive()组合出复杂的交互逻辑。读完本文你将掌握该 API 的全部工厂方法、链式配置方式、三种组合语义的底层原理以及它在当前仓库中已被标注弃用、如何平滑迁移到 v3 hook 式 API 的完整路径。Gesture 对象是什么Gesture是允许你创建和组合手势的核心对象。它本身不是一个视图组件而是描述手势应该如何被识别的配置对象创建出的手势实例不携带任何回调需要后续通过链式方法如.onStart()、.enabled()逐步完善最终作为gesture属性传给GestureDetector由后者把手势绑定到具体的视图上。最小用法示例源自 gesture.md 的 Reference 部分import { GestureDetector, Gesture } from react-native-gesture-handler; function App() { // 创建一个 Tap 手势实例默认配置、无回调 const tap Gesture.Tap(); return ( GestureDetector gesture{tap} Animated.View / /GestureDetector ); }在当前仓库源码中Gesture对象的工厂方法实现在 gestureObjects.ts每个方法都返回对应手势类的全新实例。抽象基类Gesture与实现类BaseGesture定义在 gesture.ts它通过toGestureArray()、initialize()、prepare()三个抽象方法为创建与更新 handler提供统一接口——无论是单个手势还是组合手势最终都会以相同的方式接入原生侧。创建基础手势的工厂方法Gesture提供了 10 个工厂方法每个方法都创建对应手势类型的新实例使用其默认配置且不附加任何回调。下表汇总了各方法的语义与其在源码中的对应类工厂方法对应手势类手势类型识别语义Gesture.Tap()TapGesture离散识别一次或多次点击Gesture.Pan()PanGesture连续识别拖拽panning并持续跟踪位移Gesture.LongPress()LongPressGesture离散视图被按住足够长时间后激活Gesture.Fling()FlingGesture离散移动足够快时激活甩动/轻扫Gesture.Pinch()PinchGesture连续识别双指捏合跟踪两指距离以缩放内容Gesture.Rotation()RotationGesture连续识别旋转并持续跟踪角度变化Gesture.Hover()HoverGesture连续识别鼠标或触控笔在视图上方的悬停Gesture.ForceTouch()ForceTouchGesture连续仅 iOS跟踪触摸压力仅部分 iOS 设备Gesture.Manual()ManualGesture手动无特定激活标准与事件数据状态需用状态管理器手动控制Gesture.Native()NativeGesture桥接让其他原生触摸组件参与 RNGH 手势系统以上语义均可在 gestureObjects.ts 的 JSDoc 注释中找到原始出处例如Manual的说明明确写着没有任何特定激活标准或事件数据必须使用状态管理器手动控制其状态并且当所有指针离开屏幕时它不会失败。每个手势实例在构造时都会绑定对应的原生 handler 名称例如TapGesture的handlerName为TapGestureHandler见 tapGesture.tsPanGesture为PanGestureHandler见 panGesture.ts这是前端手势对象与原生识别器iOS 侧如RNTapHandler.mAndroid 侧如TapGestureHandler.kt对接的桥梁。链式配置以 Tap 与 Pan 为例工厂方法返回的手势实例支持链式配置每个方法返回this。以TapGesture为例在 tapGesture.ts 中可以确认以下可配置项及其默认值minPointers(n)激活所需的最少触点数量默认 1numberOfTaps(count)激活所需的点击次数默认 1用于实现双击、三击maxDistance(dist)点击过程中手指允许移动的最大距离单位ptmaxDuration(ms)从按下到松开的最大时间默认 500msmaxDelay(ms)多次点击之间允许的最大间隔默认 500msmaxDeltaX(delta)/maxDeltaY(delta)点击过程中沿 X / Y 轴允许的最大位移。PanGesture的配置项见 panGesture.ts则更加丰富典型的如activeOffsetX/Y(value)手指在此范围内移动不会激活手势传负数表示负方向阈值也可传[start, end]数组failOffsetX/Y(value)激活前手指移出该范围则手势失败minDistance(distance)/minVelocity(velocity)/minVelocityX/Y激活所需的最小位移或最小速度minPointers/maxPointers参与手势的触点数量范围averageTouches(value)仅 Android将位移计算从以先落下的手指位置为准改为以所有活动触点平均位置为准与 iOS 默认行为对齐enableTrackpadTwoFingerGesture(value)仅 iOS在支持触控板的设备如 iPad上启用双指手势activateAfterLongPress(duration)Pan 允许激活前必须完成的 LongPress 时长毫秒。使用示例const pan Gesture.Pan() .minDistance(10) .activeOffsetX([-20, 20]) .onStart(() { console.log(pan started); });所有手势共有的配置与回调无论何种手势类型BaseGesture定义于 gesture.ts都提供了一套通用的链式方法状态回调onBeginhandler 开始接收触点、处于BEGAN状态、onStart手势被识别、进入ACTIVE状态、onEnd仅当此前处于ACTIVE状态时手势结束进入END状态触发、onFinalize手势成功结束或识别失败时都会触发触点级回调onTouchesDown/onTouchesMove/onTouchesUp/onTouchesCancelled注册这些回调会自动置位needsPointerData让 handler 分析触点事件流通用配置enabled(boolean)、shouldCancelWhenOutside(boolean)、hitSlop(hitSlop)、activeCursor(cursor)仅 Web支持 CSS cursor 值默认auto关系配置simultaneousWith/requireToFail/blocksHandlers用于跨组件手势交互withRef(ref)给手势对象绑定 ref以便与旧版 API 互通。连续手势Pan/Pinch/Rotation 等还额外支持onUpdate持续更新与onChange基于位移增量的变化回调。以 Pan 为例其onChange事件载荷中的changeX/changeY由 panGesture.ts 中的changeEventCalculator计算首次回调取当前translationX/Y后续回调取与上一次位移的差值。组合手势Race / Simultaneous / ExclusiveGesture还提供三种静态组合方法它们都接收一个或多个手势作为参数返回ComposedGesture类型的组合手势可以像普通手势一样交给GestureDetector。Gesture.Race(gesture1, gesture2, ...): ComposedGesture创建一个由传入手势组合而成的新手势。其中只有一个手势可以变为活动状态且对各手势的激活没有任何额外限制——第一个激活的手势会取消其余所有手势。典型场景把Pan与LongPress放进Race用户既可以快速拖动也可以在按住后触发长按菜单先识别出谁就赢。Gesture.Simultaneous(gesture1, gesture2, ...): ComposedGesture创建一个由传入手势组合而成的新手势。其中所有手势都可以同时变为活动状态互不取消。典型场景双指缩放的Pinch与单指拖动的Pan同时进行既缩放又平移。Gesture.Exclusive(gesture1, gesture2, ...): ComposedGesture创建一个由传入手势组合而成的新手势。其中只有一个手势可以变为活动状态且第一个手势优先级最高依次递减。当所有手势都处于BEGAN状态、且第二个手势的激活条件已满足时它不会立即激活而是等待第一个手势失败随后自己激活或第一个手势先激活随后自己被取消。它特别适合组合激活条件相似的手势——例如在同一个组件上同时响应单击与双击没有Exclusive时用户每次点击都会让单击手势激活从而取消双击手势而Exclusive(doubleTap, singleTap)会先等待单击手势失败后再激活双击手势。三种组合的源码级实现原理三种组合语义的具体实现位于 gestureComposition.tsComposedGestureRace的返回类型通过prepareSingleGesture把组合级的simultaneousWith/requireToFail关系合并到每个成员手势的 config 中并用relationsSnapshot保存组合前的原始关系快照。这样即使组合手势在每次渲染时被重建也不会让关系数组不断累积上一次渲染的引用内存泄漏问题见源码注释引用的 issue #3763同时保留原始引用以便在react-freeze解冻后重新解析关系issue #4238SimultaneousGesture.prepare()的逻辑很巧妙对数组中的每个手势取除它自己之外的所有手势扁平化后的列表让每个手势与其余所有手势互为simultaneousWith。通过排除自身避免了把手势与自己做同时关系——这一点对内部嵌套了ExclusiveGesture的组合尤为重要见 gestureComposition.tsExclusiveGesture.prepare()先把手势数组转换为分组数组组合手势会被toGestureArray()展开然后让每一组都等待其前面所有组失败requireToFail列表在循环中不断累加从而实现优先级按参数顺序递减的效果见 gestureComposition.ts。此外仓库中还存在一份专门讲解组合关系的文档 gesture-composition.md以及覆盖同一组件用组合 hooks、跨组件用关系属性决策树的 overview.mdx可与本文互相印证。性能优化用 useMemo 包裹手势配置原文档在 Remarks 一节特别强调建议用useMemo包裹手势配置因为它能减少 Gesture Handler 在更新手势时底层要做的工作。示例沿用原文档import React from react; function App() { const gesture React.useMemo( () Gesture.Tap().onStart(() { console.log(Number of taps:, tapNumber 1); setTapNumber((value) value 1); }), [tapNumber, setTapNumber] ); // ... }这一建议在源码中也有对应设计BaseGesture构造时会分配全局递增的gestureId见 gesture.ts。当配置被useMemo稳定缓存时依赖不变则配置不重建、gestureId不变只有当依赖变化、配置重建时gestureId才会改变从而触发 handler 的原生侧更新。换句话说useMemo让 RNGH 可以跳过配置未变化时的大量重复更新工作。当前仓库中的弃用状态与迁移路径需要特别指出在当前仓库中整套Gesture对象 API 已被标注为弃用deprecated后续版本将移除。gestureObjects.ts顶部的 JSDoc 明确写道Gesturebuilder API is deprecated and will be removed in a future version of Gesture Handler. Please migrate to the new, hook-based API.各工厂方法及组合方法均有对应的 v3 hook 替代且均有同名实现文件可查证旧版 API新版 hook API源码位置Gesture.Tap()useTapGestureuseTapGesture.tsGesture.Pan()/Pinch()/Rotation()/Fling()/LongPress()/Hover()/Manual()/Native()/ForceTouch()对应usePanGesture、usePinchGesture、useRotationGesture、useFlingGesture、useLongPressGesture、useHoverGesture、useManualGesture、useNativeGesture、useForceTouchGesture位于 v3/hooks/gestures 目录下Gesture.Race()useCompetingGesturesuseCompetingGestures.tsGesture.Simultaneous()useSimultaneousGesturesuseSimultaneousGestures.tsGesture.Exclusive()useExclusiveGesturesuseExclusiveGestures.ts组合语义在三者之间一一对应useCompetingGestures同样遵循第一个激活的手势取消其余手势useSimultaneousGestures允许全部同时激活useExclusiveGestures则按参数顺序决定优先级见 overview.mdx。新 API 的相关文档位于docs/gestures/如 use-tap-gesture.mdx与docs/composition/如 use-competing-gestures.mdx、use-simultaneous-gestures.mdx、use-exclusive-gestures.mdx旧版各手势的完整 API 参考仍保留在 legacy-gestures 目录下如 tap-gesture.md、pan-gesture.md。若仓库中同时使用了 v3 hook 与旧版 API请注意 overview.mdx 中强调的限制手势关系无法在 hook 式 API 与旧 API 之间跨体系设置。总结Gesture对象是 RNGH 声明式手势体系的基石10 个工厂方法覆盖了从点击、拖拽、长按到捏合、旋转、悬停、压力触控的完整手势类型链式配置让每个手势的激活标准、回调与关系都可精确控制而Race、Simultaneous、Exclusive三种组合语义则以极小的心智负担实现了复杂交互编排。对于新项目建议直接采用 v3 的 hook 式 APIuseTapGesture、useCompetingGestures等对于维护中的旧代码本指南给出的对应关系表可作为逐步迁移的对照依据。赞分享移动开发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 的 Gesture 对象手势创建、组合与 v3 Hook API 迁移指南react native gesture handler 的 Gesture 对象手势创建、组合与 v3 Hook API 迁移指南 Gesture 是 re移动开发UI组件电费到底花哪了Home Assistant 家庭能源管理一篇就够电费到底花哪了Home Assistant 家庭能源管理一篇就够 上个月电费 487 元空调单独贡献了多少没人答得上来。用 Home Assistant文档教程智能家居物联网Carthage命令速查手册update、bootstrap、build等10个核心命令详解Carthage命令速查手册update、bootstrap、build等10个核心命令详解 Carthage 是一款简单、去中心化的 Cocoa 依赖管理工移动开发UI组件上一篇vscode-drawio 代码链接Code Link实战指南让 Draw.io 节点与源码符号双向跳转下一篇让动作捕捉数据实时活在3D窗口里EasyMocap 实时3D可视化三步上手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考