移动开发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 旧版 APITapGestureHandler组件的完整使用指南覆盖其 7 个专属配置属性、事件数据字段、与waitFor组合实现双击/三击判定的实战写法并深入 Android/iOS 原生层源码讲解点击是如何被判定、计次与终结的。读完本文你将能精确配置单点/多点点击与连击识别并理解旧版 API 与新版 gestures APIGesture.Tap()的迁移关系。注意TapGestureHandler属于旧版 API官方文档明确指出该 API 将在未来版本中移除建议迁移到新版 gestures API对应Gesture.Tap()。迁移细节可参考 升级指南。什么是 TapGestureHandlerTapGestureHandler是一个离散型discrete手势处理器用于识别一次或多次点击。点击手势的定义是一根或多根手指短暂地触碰屏幕且在触碰期间手指相对初始触摸位置不能有明显的移动。点击次数单点、双击、三击与允许的位移距离均可通过属性配置。与连续型手势如 Pan、Pinch不同Tap 的判定是一旦满足全部条件即立即激活并结束。官方文档对这一瞬时性的表述为只有当minPointers、numberOfTaps、maxDist、maxDurationMs、maxDelayMs等条件全部满足时处理器才会 激活ACTIVE并且激活后立即进入 END 状态——这正是离散手势与连续手势在状态机上的根本区别状态流转细节见 Handler State。从源码看该组件的定义位于 TapGestureHandler.ts其 TS 类型TapGestureHandlerProps已标注deprecated并明确建议改用Gesture.Tap()export const TapGestureHandler createHandler TapGestureHandlerProps, TapGestureHandlerEventPayload ({ name: tapHandlerName, allowedProps: [...baseGestureHandlerProps, ...tapGestureHandlerProps], config: { shouldCancelWhenOutside: true, }, });注意config.shouldCancelWhenOutside: true与LongPressGestureHandler一样Tap 默认在手指移出所绑定视图范围时立即取消/失败识别大多数其他手势默认值为false参见 common-gh.md。配置属性PropertiesTapGestureHandler继承自基类 handler 的通用属性enabled、shouldCancelWhenOutside、simultaneousHandlers、waitFor、hitSlop、onGestureEvent、onHandlerStateChange等详见 Common handler properties。本节列出其专属的 7 个配置属性均可通过tapGestureHandlerProps数组见 TapGestureHandler.ts白名单校验后下发到原生层。属性类型默认值含义minPointersnumber1激活前所需放置的最少指针手指数量应为正整数maxDurationMsnumber500手指触碰后必须在多少毫秒内抬起maxDelayMsnumber500需要多次点击时两次点击之间允许的最大间隔毫秒numberOfTapsnumber1激活处理器所需完成的点击次数maxDeltaXnumber无点击过程中手指沿 X 轴允许移动的最大距离pointsmaxDeltaYnumber无点击过程中手指沿 Y 轴允许移动的最大距离pointsmaxDistnumber无点击过程中手指允许移动的最大总距离points本文档所有表示屏幕尺寸的属性与事件字段均使用points与屏幕密度无关的单位即 iOS 的 points 与 Android 的 dp与 React Native 布局系统一致见 common-gh.md。minPointers激活前需要放置的最少手指数量必须是正整数默认1。设置minPointers: 2时只有双指同时按住并快速抬起才被识别为一次点击。在 Android 实现 TapGestureHandler.kt 中minNumberOfPointers默认DEFAULT_MIN_NUMBER_OF_POINTERS 1并在每次触摸事件中通过currentMaxNumberOfPointers记录本次手势出现过的最大指针数激活条件是tapsSoFar numberOfTaps currentMaxNumberOfPointers minNumberOfPointers。maxDurationMs定义手指触碰后必须多快抬起单位毫秒默认500。若手指按住超过该时长仍未抬起本次点击判定失败。Android 侧在 startTap() 中通过主线程Handler.postDelayed(failDelayed, maxDurationMs)实现超时失败iOS 侧RNBetterTapGestureRecognizer的defaultMaxDuration 0.5秒通过scheduleCancelAfterDelay:调度超时取消。maxDelayMs当需要多次点击numberOfTaps 1时两次点击之间允许的最大时间间隔默认500。上一次点击抬起后若超过该间隔没有下一次点击则整个手势失败。iOS 源码中的默认值实际为0.2秒defaultMaxDelay 0.2Android 侧DEFAULT_MAX_DELAY_MS 200毫秒——这一点与文档标注的 500 略有出入Android 端多击时间窗更紧实测连击节奏需据此调整。Android 在 endTap() 中若未达到所需次数则postDelayed(failDelayed, maxDelayMs)等待下一次点击。numberOfTaps激活所需完成的点击次数默认1。设为2识别双击3识别三击。Android 侧DEFAULT_NUMBER_OF_TAPS 1激活判定在 endTap() 中实现见上文 minPointers 一节。maxDeltaX / maxDeltaY / maxDist三个距离约束单位均为 points无默认值即不限制maxDeltaX手指沿 X 轴允许移动的最大距离maxDeltaY手指沿 Y 轴允许移动的最大距离maxDist手指允许移动的最大总距离。任一约束被超过且处理器尚未激活则识别立即失败FAILED。Android 的位移判定在 shouldFail() 中dx lastX - startX offsetXdy同理maxDist采用平方比较dist maxDist * maxDist避免开方运算maxDeltaX/maxDeltaY/maxDist未配置时使用Float.MIN_VALUE哨兵值跳过检查。iOS 侧对应shouldFailUnderCustomCriteria同样使用TEST_MAX_IF_NOT_NAN宏对NAN默认值跳过校验。两个平台均在每次ACTION_POINTER_DOWN/UP指针增减时通过offsetX/offsetY累计偏移确保多指切换时仍以首指初始位置为基准计算位移。事件数据Event dataTapGestureHandler的事件载荷除继承基类的通用字段state、numberOfPointers等见 common-gh.md外专属字段只有坐标四元组。其 TypeScript 定义位于 GestureHandlerEventPayload.tsexport type TapGestureHandlerEventPayload { x: number; y: number; absoluteX: number; absoluteY: number; };x / y指针手指多指时为领头的那个指针当前位置相对于绑定视图的 X / Y 坐标单位 points。absoluteX / absoluteY指针当前位置**相对于窗口window**的 X / Y 坐标单位 points。官方建议当绑定视图可能因手势效果发生位移或变换时优先使用absoluteX / absoluteY而非x / y因为前者不受视图自身变换影响能提供稳定的窗口坐标。在 Android 原生层这四个字段由 TapGestureHandlerEventDataBuilder.kt 从lastRelativePositionX/Y与lastPositionInWindowX/Y取出并经PixelUtil.toDIPFromPixel把物理像素换算回 dp 单位后再写入事件。iOS 侧则由RNGestureHandlerEventExtraData在 RNTapHandler.m 中生成。实战示例用 waitFor 实现单击与双击并存由于单次点击天然会被双击手势吃掉一次双击的第一击也满足单击条件官方示例采用嵌套 waitFor的组合外层单点 Tap 通过waitFor引用内层双击 Tap使单点处理器在内层双击处理器处于BEGAN状态期间暂不激活从而让双击优先判定内层numberOfTaps{2}的处理器负责双击识别。以下示例来自仓库中的官方演示应用完整可运行版本见 apps/common-app/src/legacy/basic/multitap/index.tsx示例还叠加了LongPressGestureHandlerexport class PressBox extends Component { doubleTapRef React.createRef(); render() { return ( TapGestureHandler onHandlerStateChange{this._onSingleTap} waitFor{this.doubleTapRef} TapGestureHandler ref{this.doubleTapRef} numberOfTaps{2} View style{styles.box} / /TapGestureHandler /TapGestureHandler ); } }用法要点waitFor传 ref外层处理器传入内层处理器的doubleTapRef。waitFor的语义是只要引用的处理器还处于BEGAN状态本处理器就不得激活从而形成优先级双击先于单击被判定。内层持有ref双击处理器需要ref才能被外层引用ref通过React.createRef()创建。事件回调里判断State.ACTIVE在onHandlerStateChange中通过event.nativeEvent.state State.ACTIVE触发业务逻辑。若想进一步区分双击后不再触发单击可在单击回调中仅当state State.ACTIVE且确实为独立单击时执行配合waitFor已可覆盖绝大多数场景。waitFor与simultaneousHandlers的完整交互语义见 interactions.md。从旧版 API 迁移到 Gesture.Tap()新版 gestures API 提供了与TapGestureHandler一一对应的链式配置方法定义见 tapGesture.ts完整用法见 tap-gesture.md旧版属性新版链式方法minPointersminPointers(value)numberOfTapsnumberOfTaps(count)maxDistmaxDistance(value)maxDurationMsmaxDuration(value)maxDelayMsmaxDelay(value)maxDeltaXmaxDeltaX(value)maxDeltaYmaxDeltaY(value)新版还额外支持mouseButton(value)Web 与 Android 专属用于指定响应鼠标按键枚举值包括LEFT/RIGHT/MIDDLE/BUTTON_4/BUTTON_5/ALL可通过|组合默认MouseButton.LEFT。新版 API 的典型写法来自官方示例 tap-gesture.mdimport { Gesture, GestureDetector } from react-native-gesture-handler; const singleTap Gesture.Tap() .maxDuration(250) .onStart(() { console.log(Single tap!); }); const doubleTap Gesture.Tap() .maxDuration(250) .numberOfTaps(2) .onStart(() { console.log(Double tap!); }); return ( GestureDetector gesture{Gesture.Exclusive(doubleTap, singleTap)} View style{styles.box} / /GestureDetector );新版中单击/双击互斥通过Gesture.Exclusive(doubleTap, singleTap)组合表达比旧版的waitFor 嵌套写法更直观这也是官方推荐迁移的根本原因。原生层实现原理点击状态机如何运转AndroidKotlin状态机核心实现在 TapGestureHandler.kt其状态推进逻辑onHandle可归纳为UNDETERMINED首个ACTION_DOWN到来时initialize()记录startX/startY初始位置随后begin()进入BEGAN并通过startTap()启动maxDurationMs超时倒计时BEGAN 手指移动每次移动更新lastX/lastYshouldFail()检测位移是否超出maxDeltaX/maxDeltaY/maxDist超出即fail()BEGAN 手指抬起endTap()累加tapsSoFar若达到numberOfTaps且最大指针数满足minPointers则activate()否则启动maxDelayMs倒计时等待下一次点击激活即结束activate(force)覆写为super.activate(force); end()——这正是文档所述激活后立即 END的底层实现重置onReset()清空tapsSoFar与回调消息回到UNDETERMINED。超时失败通过主线程Handler的failDelayedRunnable 完成onCancel()中会removeCallbacksAndMessages(null)清理所有挂起的超时任务。参数更新在内部类Factory.updateConfig()中完成其中maxDeltaX/maxDeltaY/maxDist会经PixelUtil.toPixelFromDIP将 dp 换算为像素后再参与距离比较。iOSObjective-C实现iOS 侧并未直接使用系统的UITapGestureRecognizer而是在 RNTapHandler.m 中自定义了RNBetterTapGestureRecognizer。源码注释明确解释了原因UITapGestureRecognizer不允许配置maxDelay、maxDuration、minPointers、maxDelta等参数因此需要自研识别器以支持这些可配置项。其关键机制包括通过interactionsBegan/Moved/Ended/Cancelled分别对应触摸生命周期interactionsMoved中调用shouldFailUnderCustomCriteria进行位移与越界shouldCancelWhenOutside校验超时maxDuration与等待下次点击maxDelay通过dispatch_after调度 block 实现并用_pendingCancellations数组管理可取消的挂起任务源码注释指出相比performSelector:afterDelay:dispatch_after不会在UIScrollView拖拽导致的UITrackingRunLoopMode下被饿死从而保证列表滚动中点击仍能按时判定——对应 issue #3471numberOfTaps tapsSoFar maxNumberOfTouches minPointers满足时置UIGestureRecognizerStateEnded否则再次调度maxDelay倒计时maxDist以平方形式存储maxDistSq dist * dist比较时同样用平方避免每次计算平方根。常见问题与调参建议双击响应缓慢或单击误触双击需要等待maxDelayMs窗口确认是否还有第二击这是离散多击手势的固有延迟。若希望连击节奏更紧凑可同时调低maxDurationMs与maxDelayMsAndroid 侧maxDelayMs实际默认 200ms若按文档默认 500 的节奏调参需注意平台差异。点击被识别为拖动手指轻微移动即可让 Tap 失败。若发现点按老被误判为 Pan可适当放宽maxDist/maxDeltaX/maxDeltaY反之若点击过于灵敏则收紧这些阈值。手指离开视图导致点击失败Tap 的shouldCancelWhenOutside默认true手指一旦移出绑定视图边界识别即取消。若希望跨出边界仍可完成点击可显式置false。按钮类组件上使用 TapiOS 上cancelsTouchesInView默认true会在 Tap 激活时取消原生 UI 组件如UIButton的触摸避免点击穿透若需要原生控件与手势并存可将其置false见 common-gh.md。小结TapGestureHandler通过minPointers、numberOfTaps、maxDurationMs、maxDelayMs、maxDeltaX、maxDeltaY、maxDist七个配置项精确刻画一次合格的点击配合waitFor可构建单击/双击/三击等复合识别事件回调则提供x/y/absoluteX/absoluteY坐标供业务使用。其原生实现Android 的 Handler 计时状态机、iOS 的自研RNBetterTapGestureRecognizer保证了这些参数在两端的一致行为与可配置性。鉴于旧版 API 即将移除新项目应直接使用Gesture.Tap()与Gesture.Exclusive组合以获得更简洁的互斥表达与mouseButton等扩展能力。赞分享移动开发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 - 原生触控手势管理系统推荐使用React Native Gesture Handler 原生触控手势管理系统 React Native Gesture Handler 是一个由So移动开发UI组件电费到底花哪了Home Assistant 家庭能源管理一篇就够电费到底花哪了Home Assistant 家庭能源管理一篇就够 上个月电费 487 元空调单独贡献了多少没人答得上来。用 Home Assistant文档教程智能家居物联网uni-app x 中 tap-gesture-handler 点击手势组件属性、回调与实战指南uni app x 中 tap gesture handler 点击手势组件属性、回调与实战指南 本文基于 uni app 开源仓库中的组件文档 docs/c示例工程前端移动开发跨平台上一篇netprobe_lite的API文档自动生成使用Sphinx构建文档下一篇7个终极Stirling-PDF页面重组高级技巧复杂文档结构调整实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
