React Native Gesture Handler 中 Reanimated 的 Shareable 对象转换问题解析

问题背景

在使用 React Native Gesture Handler 和 Reanimated 库时，开发者可能会遇到一个特定的运行时错误："Attempted to extract from a HostObject that wasn't converted to a Shareable"。这个错误通常发生在 Android 平台上，当手势事件处理与 Reanimated 动画结合使用时。

错误本质

这个错误的根本原因是 JavaScript 和原生代码之间的对象传递问题。Reanimated 要求所有在 JavaScript 和原生代码之间传递的对象都必须是"可共享的"(Shareable)。当尝试传递一个不符合要求的对象时，就会抛出这个异常。

典型场景

这种错误经常出现在以下场景中：

1. 使用 useAnimatedGestureHandler 处理手势事件时
2. 在 runOnJS 回调中直接内联声明函数
3. 在抽屉导航(drawer)等复杂手势交互组件中

具体案例分析

在问题描述中，开发者遇到了这样的代码模式：

workletContext {
    runOnJS(() => onGestureCancel?.())();
}

这种直接在 runOnJS 中内联声明函数的做法会导致问题，因为内联函数无法被正确转换为 Shareable 对象。

解决方案

正确的做法是将需要在 runOnJS 中执行的函数预先定义在 JavaScript 上下文中，而不是内联声明。例如：

const handleGestureCancel = () => {
    onGestureCancel?.();
};

// 然后在 worklet 中使用
workletContext {
    runOnJS(handleGestureCancel)();
}

这种模式确保了函数能够被正确识别和转换，避免了 Shareable 对象转换失败的问题。

最佳实践建议

1. 避免内联函数：在 runOnJS 中避免使用内联箭头函数，预先定义好所有回调函数
2. 检查依赖项：确保所有传递到原生侧的参数都是简单类型或已被正确转换
3. 更新依赖：保持 React Native Gesture Handler 和 Reanimated 库的最新版本
4. 错误处理：在关键手势处理逻辑中添加适当的错误边界处理

底层原理

Reanimated 使用了一种特殊的机制在 JavaScript 和原生代码之间传递数据。所有需要跨边界传递的对象都必须实现特定的接口，使其成为"可共享的"。内联函数由于缺乏明确的引用和定义位置，无法满足这一要求，从而导致转换失败。

总结

React Native Gesture Handler 与 Reanimated 的结合使用虽然强大，但也需要注意对象传递的规则。通过遵循预先定义函数的原则，可以避免大多数 Shareable 对象转换问题，确保手势动画的流畅运行。