react-native-reanimated

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Native Reanimated

Overview

概述

UI-thread animation library for React Native. Reanimated 4.x runs animations on the native UI thread for guaranteed 60fps performance, replacing Framer Motion for mobile applications. Provides shared values, animated styles, declarative entering/exiting transitions, and gesture integration.

Install:

pnpm add react-native-reanimated

(included with Expo SDK 54+)

一款用于React Native的UI线程动画库。Reanimated 4.x 在原生UI线程运行动画，可保证60fps的流畅性能，可替代移动端应用中的Framer Motion。它提供共享值、动画样式、声明式进入/退出过渡以及手势集成功能。

安装：

pnpm add react-native-reanimated

（Expo SDK 54+ 已内置）

Workflows

工作流程

Adding animations to a screen:

Import from

react-native-reanimated

Animated

useSharedValue

useAnimatedStyle

withTiming

Create shared values for animated properties
Define animated styles using
```
useAnimatedStyle
```
Apply to
```
Animated.View
```
,
```
Animated.Text
```
, etc.
Check
```
useReducedMotion()
```
and skip animations when true
Test on device for smooth 60fps

Adding entering/exiting transitions:

Import layout animations:
```
FadeInDown
```
,
```
FadeOutUp
```
,
```
SlideInRight
```
, etc.
Apply
```
entering
```
and
```
exiting
```
props on
```
Animated.View
```
Chain modifiers:
```
.duration(300).easing(...).delay(100)
```
Verify reduced motion handling

为页面添加动画：

从

react-native-reanimated

导入：

Animated

、

useSharedValue

、

useAnimatedStyle

、

withTiming

为动画属性创建共享值
使用
```
useAnimatedStyle
```
定义动画样式
将样式应用到
```
Animated.View
```
、
```
Animated.Text
```
等组件
检查
```
useReducedMotion()
```
，当返回值为true时跳过动画
在真机上测试以确保60fps流畅度

添加进入/退出过渡效果：

导入布局动画：
```
FadeInDown
```
、
```
FadeOutUp
```
、
```
SlideInRight
```
等
在
```
Animated.View
```
上应用
```
entering
```
和
```
exiting
```
属性
链式调用修饰符：
```
.duration(300).easing(...).delay(100)
```
验证是否适配减少动画的设置

Guidance

指南

Core Primitives

核心原语

useSharedValue(initialValue)
: Mutable value that lives on UI thread
useAnimatedStyle(() => ({...}))
: Derives style object from shared values
withTiming(toValue, config)
: Duration-based animation
withSpring(toValue, config)
: Physics-based spring animation
withDelay(ms, animation)
: Delay before animation starts
withSequence(...animations)
: Run animations in sequence
withRepeat(animation, count, reverse)
: Repeat animation

useSharedValue(initialValue)
：存储在UI线程的可变值
useAnimatedStyle(() => ({...}))
：从共享值派生样式对象
withTiming(toValue, config)
：基于时长的动画
withSpring(toValue, config)
：基于物理规律的弹簧动画
withDelay(ms, animation)
：动画启动前的延迟
withSequence(...animations)
：按顺序运行多个动画
withRepeat(animation, count, reverse)
：重复动画

Standard Timing Configs

标准时长配置

Consistent with demo-development.md durations:

Type	Duration	Use
Fast	150ms	Micro-interactions, haptic responses
Normal	300ms	Default transitions, entering
Slow	500ms	Emphasis, screen transitions
Stagger offset	50ms per item	List item reveals

Easing:

Easing.out(Easing.cubic)

for entrances,

Easing.inOut(Easing.cubic)

for transitions,

Easing.in(Easing.cubic)

for exits.

与demo-development.md中的时长保持一致：

类型	时长	适用场景
快速	150ms	微交互、触觉反馈
常规	300ms	默认过渡、进入效果
慢速	500ms	强调效果、页面过渡
交错偏移	每项50ms	列表项逐个展示

缓动函数：进入效果使用

Easing.out(Easing.cubic)

，过渡效果使用

Easing.inOut(Easing.cubic)

，退出效果使用

Easing.in(Easing.cubic)

。

Declarative Entering/Exiting

声明式进入/退出动效

Apply directly to

Animated.View

— no parent wrapper needed (unlike AnimatePresence):

Entering:

FadeIn

FadeInDown

FadeInUp

SlideInRight

ZoomIn

Exiting:

FadeOut

FadeOutUp

FadeOutDown

SlideOutLeft

ZoomOut

Chain modifiers:

.duration(300)

.delay(100)

.easing(Easing.out(Easing.cubic))

Spring:
```
.springify().damping(15).stiffness(150)
```

可直接应用到

Animated.View

上——无需父级包装器（与AnimatePresence不同）：

进入动效：

FadeIn

、

FadeInDown

、

FadeInUp

、

SlideInRight

、

ZoomIn

退出动效：

FadeOut

、

FadeOutUp

、

FadeOutDown

、

SlideOutLeft

、

ZoomOut

链式修饰符：

.duration(300)

、

.delay(100)

、

.easing(Easing.out(Easing.cubic))

弹簧效果：
```
.springify().damping(15).stiffness(150)
```

Stagger Pattern

交错动画模式

Use

withDelay

with index multiplication:

entering={FadeInDown.delay(index * 50).duration(300)}

Or for imperative animations:

offset.value = withDelay(index * 50, withTiming(1, { duration: 300 }))

结合

withDelay

和索引相乘实现：

entering={FadeInDown.delay(index * 50).duration(300)}

或者用于命令式动画：

offset.value = withDelay(index * 50, withTiming(1, { duration: 300 }))

Accessibility — Reduced Motion

无障碍适配——减少动画

Always respect the user's accessibility preference:

const reducedMotion = useReducedMotion();

When

reducedMotion

is true:

Skip all animations (set values instantly)
Use
```
duration(0)
```
or don't apply entering/exiting props
Still show content — just don't animate it

始终尊重用户的无障碍偏好设置：

const reducedMotion = useReducedMotion();

当

reducedMotion

为true时：

跳过所有动画（直接设置值）
使用
```
duration(0)
```
或不添加进入/退出属性
仍需展示内容——只是不添加动画

Animated Components

动画组件

Use

Animated.View

Animated.Text

Animated.ScrollView

, etc. Or create animated versions:

const AnimatedPressable = Animated.createAnimatedComponent(Pressable);

使用

Animated.View

、

Animated.Text

、

Animated.ScrollView

等，或者自定义动画版本：

const AnimatedPressable = Animated.createAnimatedComponent(Pressable);

Performance

性能优化

Animate only
transform
and
opacity
— these run on the UI thread
Avoid animating
```
width
```
,
```
height
```
,
```
margin
```
,
```
padding
```
(causes layout recalculation)
Shared values update on UI thread without JS bridge overhead
```
useAnimatedStyle
```
worklets run on UI thread — keep them pure
For lists, use
```
entering
```
/
```
exiting
```
on items rather than animating the container

仅对
transform
和
opacity
属性做动画——这些属性在UI线程运行
避免对
```
width
```
、
```
height
```
、
```
margin
```
、
```
padding
```
做动画（会触发布局重计算）
共享值在UI线程更新，无需JS桥接开销
```
useAnimatedStyle
```
工作单元在UI线程运行——保持逻辑纯净
对于列表，在列表项上使用进入/退出动效，而非为容器添加动画

Best Practices

最佳实践

Use declarative
```
entering
```
/
```
exiting
```
for mount/unmount animations — simpler than manual shared values
Prefer
```
withSpring
```
for natural-feeling interactions (drag, gestures)
Prefer
```
withTiming
```
for UI transitions (screen enter, fade in)
Always check
```
useReducedMotion()
```
before applying animations
Keep standard durations consistent: 150ms / 300ms / 500ms
Use
```
withDelay(index * 50, ...)
```
for staggered list reveals
Combine with
```
react-native-gesture-handler
```
for gesture-driven animations
Use
```
Easing.out(Easing.cubic)
```
as default easing for entrances

对于挂载/卸载动画，使用声明式的
```
entering
```
/
```
exiting
```
——比手动管理共享值更简单
对于自然交互（拖拽、手势），优先使用
```
withSpring
```
对于UI过渡（页面进入、淡入），优先使用
```
withTiming
```
在应用动画前，始终检查
```
useReducedMotion()
```
保持标准时长一致：150ms / 300ms / 500ms
使用
```
withDelay(index * 50, ...)
```
实现列表项交错展示
结合
```
react-native-gesture-handler
```
实现手势驱动动画
进入效果默认使用
```
Easing.out(Easing.cubic)
```
缓动函数

Anti-Patterns

反模式

Using React Native's built-in
```
Animated
```
API instead of Reanimated
Animating layout properties (
```
width
```
,
```
height
```
,
```
margin
```
) — use
```
transform
```
and
```
opacity
```
Forgetting
```
useReducedMotion()
```
accessibility check
Running JS-thread-heavy logic inside
```
useAnimatedStyle
```
worklets
Hardcoding duration values (use constants: 150/300/500ms)
Nesting many animated views unnecessarily (performance overhead)
Using
```
setTimeout
```
for stagger instead of
```
withDelay
```
Applying entering animations without testing on real device

使用React Native内置的
```
Animated
```
API而非Reanimated
对布局属性（
```
width
```
、
```
height
```
、
```
margin
```
）做动画——应使用
```
transform
```
和
```
opacity
```
忘记做
```
useReducedMotion()
```
无障碍检查
在
```
useAnimatedStyle
```
工作单元中运行大量JS线程密集型逻辑
硬编码时长值（使用常量：150/300/500ms）
不必要地嵌套多个动画视图（会产生性能开销）
使用
```
setTimeout
```
实现交错效果而非
```
withDelay
```
未在真机上测试就应用进入动画