动画与手势

RN 动画的两种运行模式

React Native 动画存在一个根本性的性能挑战：JS 线程和 UI 线程是分离的。当 JS 线程忙于处理业务逻辑、网络请求、React 渲染时，动画帧就会丢失，表现为卡顿和掉帧。

解决方案是将动画逻辑"移到" UI 线程执行，即使 JS 线程完全冻结，动画也能保持流畅。这就是 Reanimated 3 的核心价值。在 RN 0.77.x + 新架构下，Reanimated 与 JSI 的集成更加紧密，worklet 函数的性能进一步提升。

核心名词解释

JS 驱动 vs UI 线程动画：原理对比

Animated API（内置方案）

Animated API 是 React Native 内置的动画解决方案，无需额外安装。适合简单的渐入渐出、位移动画。关键规则：始终设置 useNativeDriver: true，让动画在 UI 线程运行。

import { Animated, Easing, StyleSheet } from 'react-native';
import { useRef, useEffect } from 'react';

export function FadeInCard({ children }: { children: React.ReactNode }) {
  // useRef 保存 Animated.Value，避免每次渲染重建
  // 注意：不能用 useState 保存 Animated.Value，因为它本身就是可变的
  const opacity = useRef(new Animated.Value(0)).current;
  const translateY = useRef(new Animated.Value(20)).current;

  useEffect(() => {
    // Animated.parallel：多个动画同时运行
    Animated.parallel([
      Animated.timing(opacity, {
        toValue: 1,
        duration: 400,
        easing: Easing.out(Easing.cubic), // 先快后慢的缓出曲线
        useNativeDriver: true,              // 必须！让动画跑在 UI 线程
      }),
      Animated.timing(translateY, {
        toValue: 0,
        duration: 400,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: true,
      }),
    ]).start(); // .start() 触发动画执行
  }, []);

  return (
    <Animated.View   {/* 必须用 Animated.View，普通 View 不支持动画 */}
      style={[
        styles.card,
        {
          opacity,
          transform: [{ translateY }],
        },
      ]}
    >
      {children}
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  card: {
    backgroundColor: '#0d2137',
    borderRadius: 12,
    padding: 16,
  },
});

Reanimated 3：UI 线程动画全解

import Animated, {
  useSharedValue,    // 跨线程共享值
  useAnimatedStyle,  // 将 SharedValue 绑定到样式
  withSpring,         // 弹簧动画
  withTiming,         // 线性/缓动动画
  withSequence,       // 顺序动画
  interpolate,        // 值映射
  Extrapolation,
} from 'react-native-reanimated';
import { Gesture, GestureDetector } from 'react-native-gesture-handler';

export function DraggableCard() {
  // SharedValue：可在 JS 和 UI 线程同时读写的值
  // 通过 .value = x 赋值（不是 useState 的 setter！）
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const scale = useSharedValue(1);

  // Pan 手势：监听拖拽
  // 所有回调函数自动识别为 worklet（在 UI 线程执行）
  const gesture = Gesture.Pan()
    .onBegin(() => {
      // 按下时：弹簧放大（视觉反馈）
      scale.value = withSpring(1.05, { damping: 15, stiffness: 300 });
    })
    .onUpdate((event) => {
      // 拖拽中：直接跟随手指位置（无动画，立即响应）
      translateX.value = event.translationX;
      translateY.value = event.translationY;
    })
    .onEnd(() => {
      // 松手：弹回原位（弹簧动画）
      translateX.value = withSpring(0, { damping: 20, stiffness: 200 });
      translateY.value = withSpring(0, { damping: 20, stiffness: 200 });
      scale.value = withSpring(1);
    });

  // useAnimatedStyle：将 SharedValue 绑定为组件样式
  // 内部函数是 worklet，每次 SharedValue 变化时在 UI 线程重新执行
  const animatedStyle = useAnimatedStyle(() => {
    // interpolate：将 X 位移（-150 到 150）映射为旋转角度（-15° 到 15°）
    // Extrapolation.CLAMP：超出范围时取边界值（不会超过 ±15°）
    const rotation = interpolate(
      translateX.value,
      [-150, 0, 150],
      [-15, 0, 15],
      Extrapolation.CLAMP
    );

    return {
      transform: [
        { translateX: translateX.value },
        { translateY: translateY.value },
        { scale: scale.value },
        { rotate: `${rotation}deg` },
      ],
    };
  });

  return (
    {/* GestureDetector 包裹需要手势的组件 */}
    <GestureDetector gesture={gesture}>
      {/* Animated.View：Reanimated 的动画容器 */}
      <Animated.View style={[styles.card, animatedStyle]}>
        <Text style={styles.text}>拖拽我！</Text>
      </Animated.View>
    </GestureDetector>
  );
}

布局动画：进入/退出动画

Reanimated 的 Layout Animation 让元素的出现、消失和布局变化自动有动画，无需手动管理动画值。

import Animated, {
  FadeIn,        // 淡入进入
  FadeOut,       // 淡出退出
  SlideInRight,  // 从右侧滑入
  SlideOutLeft,  // 向左侧滑出
  ZoomIn,        // 缩放进入
  Layout,        // 布局改变动画
} from 'react-native-reanimated';

// 通知列表：条目删除时有滑出动画，其他条目有重排动画
function NotificationList({ items }: { items: Notification[] }) {
  return (
    <View>
      {items.map((item, index) => (
        <Animated.View
          key={item.id}
          entering={SlideInRight.delay(index * 50)}  // 延迟进入（错落感）
          exiting={SlideOutLeft}                      // 删除时滑出
          layout={Layout.springify()}                   // 其他元素重排时弹簧动画
          style={styles.notificationItem}
        >
          <Text>{item.message}</Text>
        </Animated.View>
      ))}
    </View>
  );
}

// 自定义进入动画（弹簧效果）
const MyEntering = ZoomIn
  .springify()         // 使用弹簧插值
  .damping(15)          // 阻尼（越小越弹）
  .stiffness(200)       // 刚度（越大越快）
  .delay(100);           // 延迟 100ms 后开始

滑动删除（Swipeable）

// 使用 Reanimated + Gesture Handler 实现 iOS 风格的左滑删除
import { Gesture, GestureDetector } from 'react-native-gesture-handler';
import Animated, {
  useSharedValue, useAnimatedStyle,
  withSpring, withTiming, runOnJS,
} from 'react-native-reanimated';
import { Dimensions } from 'react-native';

const SCREEN_WIDTH = Dimensions.get('window').width;
const DELETE_THRESHOLD = -SCREEN_WIDTH * 0.4; // 滑动超过 40% 宽度触发删除

function SwipeableItem({ item, onDelete }: { item: Item; onDelete: () => void }) {
  const translateX = useSharedValue(0);

  const gesture = Gesture.Pan()
    .activeOffsetX([-10, 10])  // 水平偏移超过 10px 才激活手势
    .onUpdate((event) => {
      // 只允许向左滑（负方向），并限制最大滑动距离
      translateX.value = Math.max(event.translationX, -SCREEN_WIDTH * 0.5);
    })
    .onEnd(() => {
      if (translateX.value < DELETE_THRESHOLD) {
        // 滑动超过阈值：继续滑出屏幕，然后触发删除回调
        // runOnJS：在 worklet 中调用 JS 函数（跨线程）
        translateX.value = withTiming(-SCREEN_WIDTH, { duration: 200 }, () => {
          runOnJS(onDelete)();
        });
      } else {
        // 未达到阈值：弹回原位
        translateX.value = withSpring(0);
      }
    });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.value }],
  }));

  return (
    <GestureDetector gesture={gesture}>
      <Animated.View style={[styles.item, animatedStyle]}>
        <Text>{item.title}</Text>
      </Animated.View>
    </GestureDetector>
  );
}