creating-reanimated-animations

React Native Reanimated 代码生成器

使用 React Native Reanimated 生成高性能动画代码。支持 v3 和 v4。

版本检测

检查项目的 package.json 以确定版本：

• v4（仅限新架构）：需要将 react-native-worklets 作为单独的依赖项
• v3（支持旧架构和新架构）：只需安装一个包

设置

Reanimated v4（最新）

npm install react-native-reanimated react-native-worklets

Babel 插件：'react-native-worklets/plugin'（必须放在插件列表的最后）。 Expo 项目：无需配置 Babel。安装后运行 npx expo prebuild。

Reanimated v3

npm install react-native-reanimated

Babel 插件：'react-native-reanimated/plugin'（必须放在插件列表的最后）。

核心模式

每个动画都遵循三个步骤：

import Animated, { useSharedValue, useAnimatedStyle, withTiming } from 'react-native-reanimated';

function Component() {
  // 1. Create shared value (lives on UI thread)
  const offset = useSharedValue(0);

  // 2. Bind to style
  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateX: offset.value }],
  }));

  // 3. Trigger animation
  const handlePress = () => {
    offset.value = withTiming(200, { duration: 500 });
  };

  return (
    <Animated.View style={[styles.box, animatedStyle]}>
      <Pressable onPress={handlePress}><Text>Move</Text></Pressable>
    </Animated.View>
  );
}

动画选择

用户需求	函数	关键参数
流畅的固定时长过渡	withTiming(to, {duration, easing})	默认值：300ms，Easing.inOut(Easing.quad)
自然的弹跳效果	withSpring(to, {mass, damping, stiffness})	默认值：mass=1，damping=10，stiffness=100
快速滑动后的惯性	withDecay({velocity, clamp})	需要手势提供初始速度
限制弹簧范围	withClamp({min, max}, withSpring(to))	v4：限制弹簧过冲
循环／脉冲／抖动	withRepeat(anim, reps, reverse)	v4 中 reps=0 表示无限循环，v3 中为 reps=-1
多步骤编排	withSequence(anim1, anim2, ...)	按顺序运行
延迟开始	withDelay(ms, anim)	延迟任意动画

**弹簧调节：**较低的 damping（5–8）= 弹跳更明显，较高的 stiffness（150–200）= 响应更迅速，较高的 mass（2–3）= 感觉更沉重。

快速模式

淡入

const opacity = useSharedValue(0);
const style = useAnimatedStyle(() => ({ opacity: opacity.value }));
// Show: opacity.value = withTiming(1);
// Hide: opacity.value = withTiming(0);

从侧面滑入

const translateX = useSharedValue(-SCREEN_WIDTH);
const style = useAnimatedStyle(() => ({
  transform: [{ translateX: translateX.value }],
}));
// Enter: translateX.value = withSpring(0);

按下时缩放

const scale = useSharedValue(1);
const style = useAnimatedStyle(() => ({
  transform: [{ scale: scale.value }],
}));
// In:  scale.value = withSpring(0.95);
// Out: scale.value = withSpring(1);

插值

import { interpolate, Extrapolation } from 'react-native-reanimated';

const style = useAnimatedStyle(() => ({
  opacity: interpolate(scrollY.value, [0, 100], [1, 0], Extrapolation.CLAMP),
  transform: [{
    scale: interpolate(scrollY.value, [0, 100], [1, 0.8], Extrapolation.CLAMP),
  }],
}));

与滚动关联的动画

const scrollY = useSharedValue(0);
const scrollHandler = useAnimatedScrollHandler({
  onScroll: (event) => { scrollY.value = event.contentOffset.y; },
});
<Animated.ScrollView onScroll={scrollHandler}>{children}</Animated.ScrollView>

或者使用 useScrollOffset（v4）／useScrollViewOffset（v3）实现更简单的效果：

const ref = useAnimatedRef<Animated.ScrollView>();
const scrollOffset = useScrollOffset(ref); // auto-tracks scroll position
<Animated.ScrollView ref={ref}>{children}</Animated.ScrollView>

布局动画（挂载／卸载）

内置预设——无需共享值：

import Animated, { FadeIn, SlideInRight, SlideOutLeft } from 'react-native-reanimated';

<Animated.View entering={FadeIn.duration(400).delay(100)} exiting={SlideOutLeft.duration(300)}>
  {content}
</Animated.View>

预设：FadeIn/Out、SlideIn/OutLeft/Right/Up/Down、ZoomIn/Out、BounceIn/Out、FlipInEasyX/Y、LightSpeedIn/Out、PinwheelIn/Out、RollIn/Out、RotateIn/Out、StretchIn/Out。

修饰符：.duration(ms)、.delay(ms)、.springify()、.damping(n)、.stiffness(n)、.randomDelay()、.reduceMotion()、.withCallback()。

布局过渡（位置／尺寸变化）

在组件的位置或尺寸变化时生成动画：

import { LinearTransition, SequencedTransition } from 'react-native-reanimated';

<Animated.View layout={LinearTransition.springify().damping(15)} />

过渡：LinearTransition、SequencedTransition、FadingTransition、JumpingTransition、CurvedTransition、EntryExitTransition。

关键帧动画（复杂的进入／退出效果）

import { Keyframe } from 'react-native-reanimated';

const enteringAnimation = new Keyframe({
  0: { opacity: 0, transform: [{ translateY: -50 }] },
  50: { opacity: 0.5, transform: [{ translateY: -25 }], easing: Easing.out(Easing.quad) },
  100: { opacity: 1, transform: [{ translateY: 0 }] },
}).duration(500);

<Animated.View entering={enteringAnimation}>{content}</Animated.View>

如需自定义动画、布局过渡和列表动画，请阅读 references/layout-animations.md。

CSS 动画（仅限 v4）

直接使用样式属性声明类似 CSS 的动画：

<Animated.View style={{
  animationName: {
    from: { opacity: 0, transform: [{ translateY: -20 }] },
    to: { opacity: 1, transform: [{ translateY: 0 }] },
  },
  animationDuration: '500ms',
  animationTimingFunction: 'ease-out',
}} />

支持的属性：animationName、animationDuration、animationDelay、animationIterationCount、animationDirection、animationFillMode、animationPlayState、animationTimingFunction。

CSS 过渡（仅限 v4）

样式值变化时自动触发过渡：

<Animated.View style={{
  width: isExpanded ? 200 : 100,
  transitionProperty: 'width',
  transitionDuration: '300ms',
  transitionTimingFunction: 'ease-in-out',
}} />

多个属性：transitionProperty: ['width', 'opacity', 'transform']，并设置匹配的 transitionDuration: ['300ms', '200ms', '500ms']。

如需 CSS 动画／过渡的详细参考（关键帧、计时函数、示例），请阅读 references/css-animations-detailed.md。

共享元素过渡（实验性）

在导航期间，为屏幕间的组件设置动画：

// Screen A
<Animated.Image sharedTransitionTag={`photo-${id}`} source={...} />

// Screen B (same tag)
<Animated.Image sharedTransitionTag={`photo-${id}`} source={...} />

需要 @react-navigation/native-stack 和功能标志。如需设置和自定义相关说明，请阅读 references/shared-element-transitions.md。

手势集成

如需拖动、捏合、快速滑动及其他手势驱动的动画，请阅读 references/gesture-patterns.md。

需要：react-native-gesture-handler，并在应用根节点使用 <GestureHandlerRootView>。

完整 API 参考

如需查看完整的钩子签名、动画参数、v3 与 v4 的差异以及高级 API，请阅读 references/api-reference.md。

Worklets 与高级 API

如需了解 worklet、'worklet' 指令、runOnJS/runOnUI、useAnimatedReaction、useFrameCallback、measure、dispatchCommand 以及性能技巧，请阅读 references/worklets-advanced.md。

实际组件模式

如需查看手风琴、底部面板、翻转卡片和 FAB 的完整实现，请阅读 references/component-patterns.md。

测试、颜色与支持的属性

如需了解如何使用 Jest 测试动画、使用 interpolateColor 为颜色添加动画，以及按平台划分的完整可动画属性列表，请阅读 references/testing-and-properties.md。

规则

• 始终使用 Animated.View/Text/Image/ScrollView/FlatList，绝不要对普通 RN 组件添加动画
• v4：使用 runOnJS/runOnUI（重新导出），或从 react-native-worklets 导入 scheduleOnRN/scheduleOnUI
• v3：对于繁重的 JS 线程逻辑，使用 runOnJS(fn)()
• 除非明确需要超出范围的插值，否则始终在 interpolate 中使用 Extrapolation.CLAMP
• 组合使用：withSequence(withTiming(1.2, {duration: 100}), withSpring(1))
• 使用 useReducedMotion() 遵循无障碍设置
• 在真实设备上测试——模拟器的性能差异很大
• v4：useAnimatedKeyboard 已弃用 → 使用 react-native-keyboard-controller

---

基于 Software Mansion 的 react-native-reanimated（MIT 许可证）