把 PanResponder 和 GestureHandler 的抽象对齐到一套手势模型里，我们踩过的坑和最终选型

Q: PanResponder 适配器在 Android 和 iOS 上的行为是否完全一致？

不完全一致，但差异被控制在适配器内部。比如 Android 上的 onPanResponderTerminate 触发时机与 iOS 不同（Android 更激进地在父视图拦截时触发），适配器对 terminate 的处理统一映射到 cancelled 状态，上层业务无感知。但如果你在 PanResponder 路径下使用 numberOfPointers 做多指手势，Android 和 iOS 在手指计数上存在已知的原生差异，适配器无法补偿。

如果你正在维护一个同时跑在 React Native 旧架构和新架构上的跨端组件库，手势系统一定会成为你代码里最不“跨端”的那部分。PanResponder 和 React Native Gesture Handler 的事件模型、坐标体系、状态流转机制存在根本差异，直接写两套逻辑维护成本翻倍，硬套同一套抽象又会在边界 case 上连环爆炸。我们最终选型的结论是：以内置 GestureDetector 的手势模型为统一抽象层，向上提供声明式 API，向下通过适配器抹平 PanResponder 的差异，同时保留 PanResponder 作为旧架构 fallback，但这套方案的落地过程远比听起来复杂得多。

为什么 PanResponder 和 GestureHandler 无法直接对齐

这个问题在写第一行适配代码之前就需要彻底搞清楚，否则后面所有“统一抽象”都是空中楼阁。两者的差异不是接口风格不同，而是底层的事件机制、状态模型和坐标语义存在结构性分歧。

事件响应链的根本差异。 PanResponder 基于 React Native 的 touch 事件系统，走的是一条明确的事件捕获-冒泡链路。一个手势是否被某个视图“抓住”，取决于 onStartShouldSetPanResponder 的返回值，并且一旦某个视图成为响应者，父视图就无法再拦截。Gestures Handler 则完全绕开了这条链路，它在 native 侧直接接管了手势识别，通过 simultaneousHandlers 和 waitFor 等声明式规则来协调多个手势之间的关系。这意味着：在 PanResponder 中你可以通过层级嵌套来实现手势优先级，但在 Gesture Handler 中你必须在同一个层级上声明规则，两种心智模型完全不同。

状态机的粒度不对等。 PanResponder 的状态转换非常简单：grant → move → release/terminate，就这三个阶段。而 Gesture Handler 的手势有 UNDETERMINED → BEGAN → ACTIVE → END/FAILED/CANCELLED 六个状态，其中 UNDETERMINED 和 BEGAN 的区分特别关键——一个手势可以先进入 BEGAN 状态然后失败回退，这在 PanResponder 里完全没有对应概念。如果你试图把 Gesture Handler 的状态映射到 PanResponder 的模型上，必然会丢失 FAILED 状态的信息，导致某些边界 case（比如点击和滑动手势的冲突处理）行为不一致。

坐标体系的不兼容。 这一点最容易踩坑，也最容易在生产环境出问题。PanResponder 的 gestureState 提供了 dx/dy（从手势开始到当前的累计位移）、moveX/moveY（相对屏幕的绝对坐标）、x0/y0（手势起始点在响应视图内的相对坐标）。而 Gesture Handler 的 Pan 手势中，translationX/translationY 是激活后相对于 BEGAN 点的位移——注意，是激活后，不是从手指按下开始算。如果一个手势需要经过一定距离阈值才激活（比如 minDist: 10），那么 PanResponder 的 dx 会包含这 10px，而 Gesture Handler 的 translationX 不会。在 2023 年的一次更新中，Gesture Handler 确实引入了 unfilteredTranslationX 来解决这个问题，但这意味着你需要明确选择使用哪个值，而不是简单的一对一映射。

我们尝试过的三种方案及失败原因

方案一：以 PanResponder 为基准向下适配。 这个思路很直觉——既然 PanResponder 是 RN 内置的，用它作为统一抽象层，然后在需要 Gesture Handler 的地方做桥接。但很快发现这是反向的。PanResponder 的模型太简陋了，根本没有 onBegin 和 onEnd 的区分（它的 onPanResponderGrant 对应的是手势捕获，不是手势激活），也没有手势失败的概念。当用户快速滑动后松手触发惯性滚动时，PanResponder 只能收到一个 onPanResponderRelease，但 Gesture Handler 可以区分 END（手势成功完成）和 FAILED（手势未能激活）。如果你用 PanResponder 作为统一模型，那么所有使用 Gesture Handler 的场景都会降级到更粗糙的状态信息，手势冲突处理的灵活性也会丧失。

方案二：双轨制，根据平台和架构自动切换。 在旧架构 Android/iOS 上使用 PanResponder，在新架构或特定场景下切换到 Gesture Handler。这个方案在逻辑上没问题，但工程上很快失控。任何对手势行为的调整都需要在两个完全不同的实现里各改一遍，而且两者的行为差异会导致同一个组件在不同环境下表现不一致——测试用例都得写两套，bug 经常是“只在 iOS 旧架构会出现”。三个月后我们放弃了，维护成本远超预期。

方案三：完全拥抱 Gesture Handler，放弃 PanResponder。 这是最干净的方案，但在我们维护的组件库中不可行。一部分接入方仍在使用 React Native 0.66 甚至更早版本，且没有集成 react-native-gesture-handler。作为组件库，我们不能强制宿主应用引入额外的 native 依赖。所以这个方案被否决，但方向是对的——以 Gesture Handler 的模型为抽象基准。

最终落地：声明式 API + 适配器模式

最终的架构分三层：最上层是面向组件开发者的声明式手势 API，中间是统一手势模型（对齐到 Gesture Handler 的状态机和语义），底层是两个适配器——Gesture Handler 适配器几乎是直通，PanResponder 适配器则需要做大量的模拟和补偿。

声明式 API 的设计。 我们不直接暴露 PanResponder 的回调或 Gesture Handler 的 onStart/onUpdate/onEnd，而是定义了一套统一的手势事件类型：

interface UnifiedGestureEvent {
  // 手势阶段
  state: 'idle' | 'began' | 'active' | 'ended' | 'failed' | 'cancelled';
  
  // 位移（对齐 Gesture Handler 的语义，从 BEGAN 开始计算）
  translationX: number;
  translationY: number;
  
  // 速度
  velocityX: number;
  velocityY: number;
  
  // 绝对坐标（相对页面）
  absoluteX: number;
  absoluteY: number;
  
  // 手势激活时的起始坐标
  anchorX: number;
  anchorY: number;
  
  // 手指数量
  numberOfPointers: number;
}

这套类型直接映射到 Gesture Handler 2.x 的 GestureEvent 结构，但去掉了 native 侧特有的字段（如 handlerTag、target），保留了所有对 UI 逻辑有用的信息。组件开发者只需要处理这六种状态，不再需要关心底层是 PanResponder 还是 Gesture Handler。

PanResponder 适配器的关键补偿逻辑。 这是整个方案中最复杂的部分。PanResponder 没有 began 状态，我们需要在适配器里模拟一个激活阈值。具体做法是：在 onPanResponderGrant 时进入 idle 状态，在 onPanResponderMove 中检测位移是否超过阈值（默认为 4px，与 Gesture Handler 的 activateAfterLongPress 类似但不完全相同），超过后触发 began 状态，并将当前位置记录为锚点，后续的 translationX/Y 都基于这个锚点重新计算。

// PanResponder 适配器的核心状态机简化版
class PanResponderAdapter {
  private state: UnifiedGestureState = 'idle';
  private anchorX: number = 0;
  private anchorY: number = 0;
  private activationThreshold: number = 4;

  handleMove(gestureState: PanResponderGestureState) {
    if (this.state === 'idle') {
      const dist = Math.hypot(gestureState.dx, gestureState.dy);
      if (dist >= this.activationThreshold) {
        this.state = 'began';
        this.anchorX = gestureState.moveX - gestureState.dx;
        this.anchorY = gestureState.moveY - gestureState.dy;
        this.emit({ state: 'began', translationX: 0, translationY: 0, ... });
      }
      return;
    }

    if (this.state === 'began' || this.state === 'active') {
      this.state = 'active';
      const translationX = gestureState.moveX - this.anchorX;
      const translationY = gestureState.moveY - this.anchorY;
      this.emit({
        state: 'active',
        translationX,
        translationY,
        absoluteX: gestureState.moveX,
        absoluteY: gestureState.moveY,
        velocityX: gestureState.vx,
        velocityY: gestureState.vy,
        anchorX: this.anchorX,
        anchorY: this.anchorY,
        numberOfPointers: gestureState.numberActiveTouches,
      });
    }
  }

  handleRelease() {
    if (this.state === 'active') {
      this.emit({ state: 'ended', ... });
    } else if (this.state === 'began') {
      // 手势已激活但在释放时未产生足够位移，视为失败
      this.emit({ state: 'failed', ... });
    }
    this.state = 'idle';
  }

  handleTerminate() {
    if (this.state !== 'idle') {
      this.emit({ state: 'cancelled', ... });
    }
    this.state = 'idle';
  }
}

手势冲突处理的声明式协调。 这是 PanResponder 适配器最大的短板，也是我们选择“对齐到 Gesture Handler 模型”而非反过来做的核心原因。在 Gesture Handler 中，手势间的依赖关系通过 simultaneousHandlers、waitFor、blocksExternalGesture 等声明式属性来配置，这些属性的语义是精确的、可组合的。PanResponder 完全没有等价的机制，我们只能在一个父级 PanResponder 中手动判断多个子手势的交互状态。

我们的折中方案是：在适配器层提供 simultaneous 和 waitFor 的有限实现。同一容器内的多个 PanResponder 适配器实例会注册到一个共享的协调器中，当一个手势的 began 触发时，协调器检查是否有 waitFor 依赖指向其他手势，如果有则延迟激活。这个实现不支持跨容器协调（那需要修改原生层的 touch 分发逻辑，超出了适配器的能力范围），但在绝大多数使用场景下已经够用。

性能与边界 case

切换到适配器模式后，我们最担心的就是 PanResponder 路径下的性能退化。毕竟在原始实现中，onPanResponderMove 是直接在 native 侧通过 bridge 回调 JS，而适配器又加了一层状态判断和坐标重计算。实际测试下来，在 iPhone 12（iOS 15）和 Pixel 5（Android 12）上，适配器带来的额外 JS 帧耗时在 0.1-0.3ms 之间，远低于 16.7ms 的帧预算，对 60fps 的拖拽跟随没有可感知的影响。关键优化点在于：适配器内部不做任何内存分配（复用事件对象），以及状态机使用整数枚举而非字符串比较。

真正头疼的是边界 case。举两个我们花了一周以上才解决的：

快速连续手势的状态残留。 用户快速点击两次，第一次触发 began → failed，第二次手指按下时，PanResponder 的 grant 触发但适配器还在 idle 状态。如果第二次点击的 onPanResponderGrant 在第一次的 handleRelease 之前到达（bridge 异步导致的事件乱序），适配器会错误地忽略第二次手势。解决方案是在适配器中维护一个递增的 gestureId，每次 grant 时生成新 ID，所有后续事件都校验 ID 是否匹配。

ScrollView 内的手势吸收。 当一个 PanResponder 放置在 ScrollView 内时，滚动手势会触发 onPanResponderTerminate 而不是 onPanResponderRelease。适配器需要正确处理 terminate → cancelled 的状态转换，并且确保 cancelled 状态不会触发业务层的“手势完成”逻辑。这个在 Gesture Handler 中天然正确（滚动会触发 CANCELLED），但在 PanResponder 适配器中需要显式处理。

选型反思

回顾整个选型过程，最关键的决策点不是技术方案本身，而是对“统一手势模型的基准应该是什么”这个问题的回答。我们选择对齐到 Gesture Handler 的模型，不是因为它是第三方库就更好，而是因为它的状态机更完整、语义更清晰，而且它是 RN 手势系统的未来方向（新架构的 Fabric 渲染器天然偏好 Gesture Handler 的事件机制）。PanResponder 作为 fallback 被保留，但它被降级为一个“模拟层”，不再影响上层 API 的设计。

这个决策的代价是 PanResponder 适配器的复杂度显著增加，以及某些高级特性（跨容器手势协调、原生驱动的手势动画）在 PanResponder 路径下不可用。但对于一个需要同时支持新旧架构、兼容有无 Gesture Handler 依赖的组件库来说，这是当前约束下的最优解。如果宿主应用已经全面升级到新架构并集成了 Gesture Handler 2.x，适配器会自动走直通路径，不会有任何额外开销。

常见问题

为什么不直接用 react-native-gesture-handler 作为强制依赖，省去所有适配工作？

因为组件库的定位决定了不能强制宿主应用引入 native 依赖。部分企业级应用对第三方 native 模块有严格的审查流程，而且一些轻量级场景（比如纯展示页面）完全不需要 Gesture Handler 的复杂手势能力。保留 PanResponder 路径可以让组件库在最低 React Native 0.66、无额外依赖的环境下正常运行，覆盖更多接入场景。

PanResponder 适配器在 Android 和 iOS 上的行为是否完全一致？

不完全一致，但差异被控制在适配器内部。比如 Android 上的 onPanResponderTerminate 触发时机与 iOS 不同（Android 更激进地在父视图拦截时触发），适配器对 terminate 的处理统一映射到 cancelled 状态，上层业务无感知。但如果你在 PanResponder 路径下使用 numberOfPointers 做多指手势，Android 和 iOS 在手指计数上存在已知的原生差异，适配器无法补偿。

新架构的 Fabric 渲染器对这套方案有什么影响？

Fabric 下 React Native 的 touch 事件系统有重大变化，PanResponder 的实现基于新的 NativeTouchEvent，某些行为与旧架构的 Paper 渲染器不同。我们在适配器中增加了渲染器检测逻辑（通过 global.__reactInternalInstance 的特定属性判断），对 Fabric 下的 PanResponder 行为做了额外的兼容处理。长期来看，新架构普及后我们会逐步降低 PanResponder 路径的维护优先级，最终可能将其标记为 deprecated。