animate-expo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Animations in Expo

在Expo中构建动画

A construction skill for React Native. It turns a request for motion into an implementation that survives a strict review on a real device — not in the simulator, not on a flagship phone in dev mode.

Mobile changes three things about animation, and everything in this skill follows from them:

There is no hover. Every affordance the web puts in hover has to live in press, position, or nothing.
There are two runtimes. Worklets (Reanimated 4) makes this explicit: the React Native runtime, where React renders and your app logic runs, and the UI runtime, where worklets run every frame (plus optional worker runtimes for background work). An animation that touches the RN runtime stutters the moment the app does anything else. The whole craft is keeping motion on the UI runtime.
The user's finger is on the element. Gestures are the primary input, so interruptibility and velocity handoff aren't polish — they're the baseline.

这是一项React Native开发技能，能将动效需求转化为可通过真实设备严格测试的实现——而非仅在模拟器或开发模式下的旗舰手机上可行。

移动端动画有三个核心差异，本技能的所有内容均围绕这些差异展开：

没有悬停交互。网页中依赖悬停的所有交互提示，都必须转化为按压、位置提示，或直接移除。
存在两个运行时。Worklets（Reanimated 4）明确了这一点：React Native运行时负责React渲染和应用逻辑执行，UI运行时负责每帧运行worklets（还可选择使用worker运行时处理后台任务）。一旦动画触及RN运行时，当应用执行其他操作时就会出现卡顿。动画开发的核心就是让动效始终运行在UI运行时。
用户手指直接接触元素。手势是主要输入方式，因此动画的可中断性和速度衔接并非锦上添花，而是基本要求。

Operating Posture

操作准则

You are a senior mobile engineer building the animation yourself. Make the call, state the reasoning in one line, write the code. Never present motion options as a menu.

Two failure modes, and the first is worse:

Animating something that shouldn't animate. The gate below exists to produce zero lines of code sometimes.
Animating the right thing on the wrong thread — a
```
setState
```
per frame, a
```
PanResponder
```
, an animated
```
height
```
. It looks fine in dev on your phone and drops to 20fps on a three-year-old Android.

你是一名资深移动端工程师，需要亲自实现动画。直接做出决策，用一句话说明理由，然后编写代码。绝不要将动效选项做成菜单供选择。

两种失败模式，第一种更为严重：

为不该加动画的元素添加动画。下方的判断标准就是为了避免这种情况，有时你应该写出零行代码。
为正确的元素选择了错误的线程执行动画——比如每帧调用
```
setState
```
、使用
```
PanResponder
```
、对
```
height
```
做动画。在你的开发手机上看起来没问题，但在三年前的安卓设备上帧率会降到20fps。

Hard Rules

硬性规则

Run the sequence in order. Steps 1 and 2 gate everything.
Reanimated, not core
Animated
. Core
```
Animated
```
can't be driven by a gesture without crossing the bridge, and
```
useNativeDriver
```
refuses anything but transform and opacity anyway. Reanimated worklets run on the UI thread and keep running while JS is busy.
No approximated values. Curves and spring configs come from the tables below.
Reduced motion ships with the animation, not as a follow-up.
Feel is judged on a release build on the slowest device you support. Nothing else counts as verified.

按顺序执行流程。步骤1和步骤2是所有后续操作的前提。
使用Reanimated，而非核心
Animated
。核心
```
Animated
```
无法在不跨桥的情况下由手势驱动，而且
```
useNativeDriver
```
只支持transform和opacity属性。Reanimated worklets运行在UI线程，即使JS线程繁忙也能持续运行。
不使用近似值。曲线和弹簧配置必须使用下方表格中的参数。
简化动效需与动画同步交付，而非后续补充。
动画体验需在你支持的最慢设备的发布版本中验证。其他任何环境的测试结果都不算数。

The Build Sequence

构建流程

1. Should this animate at all?

1. 是否真的需要添加动画？

Frequency	Decision
100+ times/day — tab switches, keyboard open/close, scrolling, toggles in settings	No animation. Platform default or nothing. Stop here.
Tens of times/day — press feedback, list navigation, row selection	Near-imperceptible only: under 150ms, or nothing
Occasional — sheets, modals, toasts, onboarding steps	Standard animation
Rare / first-time — success states, empty-state illustrations, celebration	The delight budget lives here

Tab switches never slide. Tabs are peers, not a hierarchy — sliding implies depth that isn't there, and the user pays for it dozens of times a session.

animation: 'none'

If the request fails this gate, say so and don't write it.

使用频率	决策
每天100次以上——切换标签、键盘开合、滚动、设置中的开关	不添加动画。使用平台默认效果或直接移除。到此为止。
每天数十次——按压反馈、列表导航、行选择	仅添加几乎难以察觉的动画：时长低于150ms，或直接不添加
偶尔使用——底部弹窗、模态框、提示框、引导步骤	使用标准动画
极少/首次使用——成功状态、空状态插图、庆祝动画	可在此处使用「愉悦预算」

标签切换绝不使用滑动动画。标签是同级关系，而非层级关系——滑动动画暗示了不存在的深度，而且用户每次会话要为此付出数十次等待成本。设置

animation: 'none'

。

如果需求未通过此判断，直接说明并停止开发。

2. What is the purpose?

2. 动画的目的是什么？

Name it in one word before continuing: feedback, spatial consistency, state indication, preventing a jarring change, explanation, or delight (rare tier only).

Can't name it? Don't build it.

在继续之前用一个词明确目的：反馈、空间一致性、状态指示、避免突兀变化、解释说明或愉悦感（仅适用于极少使用的场景）。

无法明确目的？不要开发。

3. Pick the tool — cheapest that works

3. 选择工具——用最简单的工具实现需求

Walk down; stop at the first that fits.

Need	Tool
A state-driven change with no gesture — press, toggle, color, a value flipping	Reanimated CSS transition ( `transitionProperty` in the style)
Loop, multi-stage, or plays on mount with no state change	Reanimated CSS animation ( `animationName` keyframes)
An element mounting or unmounting, or a list reflowing	Layout animations ( `entering` / `exiting` / `itemLayoutAnimation` )
Anything a finger touches, or anything derived from scroll	`useSharedValue` + `Gesture` + `useAnimatedStyle`
Screen to screen	Native stack options in Expo Router. Never hand-roll this
A bottom sheet that is its own screen	`presentation: 'formSheet'` — it's a real UISheetPresentationController, free and correct
Tab bar	`NativeTabs` (from `expo-router/unstable-native-tabs` ) — the platform's real tab bar, its behaviors and transitions included
Context menu, press-and-hold preview	`Link.Menu` / `Link.Preview` (Expo Router, iOS-only) — native menus and peek, never rebuilt in JS
Header that collapses into a large title	`headerLargeTitleEnabled` on the native stack (iOS-only; `headerLargeTitle` is deprecated) — not a scroll worklet
Pull to refresh	`RefreshControl` — hand-roll only when it's a signature interaction (see the threshold recipe)
UI that tracks the keyboard	`react-native-keyboard-controller` — the keyboard's real position, frame by frame, on the UI thread
Vector illustration, celebration, empty state	Lottie — for illustration only, never for UI state
A huge animated scene, freeform drawing	`@shopify/react-native-skia` — a canvas, for when the view hierarchy itself is the bottleneck

Reach for a shared value only when the value is continuous or interruptible. A press scale is a CSS transition; a drag is a shared value. Using a worklet for a two-state toggle is the mobile equivalent of installing a motion library for a fade.

Dependencies. Install with

npx expo install <package>

— it resolves the version that matches the project's SDK, which plain

npm install

won't:

Need	Package
Animation	`react-native-reanimated` + `react-native-worklets`
Gestures	`react-native-gesture-handler`
Navigation, sheets, native tabs, menus	`expo-router`
Haptics	`expo-haptics`
Keyboard-following UI	`react-native-keyboard-controller` (needs `KeyboardProvider` at the root — see the keyboard recipe)
Illustration, celebration	`lottie-react-native`
Very large animated scenes, custom drawing	`@shopify/react-native-skia`

按顺序选择，找到第一个符合需求的工具即停止。

需求	工具
无手势的状态驱动变化——按压、开关、颜色、值切换	Reanimated CSS过渡（样式中的 `transitionProperty` ）
循环动画、多阶段动画或挂载时自动播放且无状态变化	Reanimated CSS动画（ `animationName` 关键帧）
元素挂载/卸载，或列表重排	布局动画（ `entering` / `exiting` / `itemLayoutAnimation` ）
任何手指触摸的元素，或基于滚动的动效	`useSharedValue` + `Gesture` + `useAnimatedStyle`
屏幕间过渡	Expo Router中的原生栈配置。绝不要手动实现
作为独立屏幕的底部弹窗	`presentation: 'formSheet'` ——这是原生的UISheetPresentationController，免费且符合规范
标签栏	`NativeTabs` （来自 `expo-router/unstable-native-tabs` ）——平台原生标签栏，包含其所有行为和过渡效果
上下文菜单、长按预览	`Link.Menu` / `Link.Preview` （Expo Router，仅iOS）——原生菜单和预览功能，绝不要用JS重新实现
可折叠为大标题的头部	原生栈的 `headerLargeTitleEnabled` （仅iOS； `headerLargeTitle` 已废弃）——不要用滚动worklet实现
下拉刷新	`RefreshControl` ——仅当这是标志性交互时才手动实现（参考阈值方案）
跟随键盘的UI	`react-native-keyboard-controller` ——键盘的实时位置，逐帧更新，运行在UI线程
矢量插图、庆祝动画、空状态	Lottie——仅用于插图，绝不要用于UI状态
大型动画场景、自由绘制	`@shopify/react-native-skia` ——画布工具，适用于视图层级本身成为瓶颈的场景

仅当值是连续或可中断时才使用共享值。按压缩放用CSS过渡；拖拽用共享值。为双状态开关使用worklet，相当于在网页中为淡入效果安装动效库，属于过度设计。

依赖安装。使用

npx expo install <package>

安装——它会匹配项目SDK的版本，而普通

npm install

不会：

需求	包
动画	`react-native-reanimated` + `react-native-worklets`
手势	`react-native-gesture-handler`
导航、弹窗、原生标签栏、菜单	`expo-router`
触觉反馈	`expo-haptics`
跟随键盘的UI	`react-native-keyboard-controller` （需要在根节点添加 `KeyboardProvider` ——参考键盘方案）
插图、庆祝动画	`lottie-react-native`
大型动画场景、自定义绘制	`@shopify/react-native-skia`

4. Pick the properties

4. 选择动画属性

transform
and
opacity
are free. Everything else is a layout pass.
```
width
```
,
```
height
```
,
```
margin
```
,
```
padding
```
,
```
flex
```
,
```
top
```
,
```
left
```
,
```
gap
```
re-run Yoga on every frame for that node and its siblings.
The one exception: an absolutely positioned element with no children — a tab pill, a progress bar fill. It's out of flow, so nothing else re-lays-out, and animating
```
width
```
keeps the corner radius that
```
scaleX
```
would smear.
Never
scale(0)
. Start from
```
scale(0.9–0.97)
```
+
```
opacity: 0
```
. Nothing in the real world appears from nothing.
transform
is an array and order matters —
```
[{ translateY }, { scale }]
```
scales after moving; reversed, the translate gets scaled too. Keep translate first unless you want the multiplication.
Android shadows are
elevation
, and animating elevation re-renders the shadow every frame. Animate opacity of a pre-shadowed layer instead.
Never animate
BlurView
intensity. On Android it re-renders the blur each frame. Crossfade the opacity of a static
```
BlurView
```
instead.
Percentages work in
translate
and are relative to the element's own size —
```
translateY('100%')
```
moves a sheet by its own height whatever its content.

transform
和
opacity
是无成本的。其他所有属性都会触发布局重排。
```
width
```
、
```
height
```
、
```
margin
```
、
```
padding
```
、
```
flex
```
、
```
top
```
、
```
left
```
、
```
gap
```
会在每帧为该节点及其兄弟节点重新运行Yoga布局引擎。
唯一例外：无子元素的绝对定位元素——比如标签指示器、进度条填充。它脱离了布局流，因此不会触发其他元素重排，而且对
```
width
```
做动画能保持
```
scaleX
```
会模糊的圆角。
绝不要使用
scale(0)
。从
```
scale(0.9–0.97)
```
+
```
opacity: 0
```
开始。现实世界中没有东西是从无到有的。
transform
是数组且顺序重要——
```
[{ translateY }, { scale }]
```
会先移动再缩放；反转顺序的话，位移会被缩放。除非需要乘法效果，否则保持位移在前。
安卓阴影使用
elevation
，而动画
elevation
会每帧重新渲染阴影。改为对预添加阴影的图层做透明度动画。
绝不要对
BlurView
的强度做动画。在安卓上会每帧重新渲染模糊效果。改为交叉淡入静态
```
BlurView
```
的透明度。
translate
支持百分比，且相对于元素自身尺寸——
```
translateY('100%')
```
会让弹窗移动自身高度的距离，无论内容是什么。

5. Timing or spring

5. 选择时序动画还是弹簧动画

If a finger was involved, use a spring. Springs carry velocity through an interruption; timing curves restart. Everything else uses timing.

Reanimated's spring takes Apple's two designer parameters directly — use this form, not mass/stiffness/damping:

Interaction	Config
Default settle, no overshoot	`{ duration: 400, dampingRatio: 1 }`
Reposition / snap back after a drag	`{ duration: 400, dampingRatio: 0.8, velocity }`
Sheet, drawer	`{ duration: 300, dampingRatio: 0.8, velocity }`
Must not pass a hard edge	add `overshootClamping: true`

Bounce only when the gesture carried momentum. Overshoot on a menu that faded in feels wrong; overshoot on a card you flicked feels right.

Easing, for everything without a finger on it:

Situation	Easing
Entering or exiting	`ease-out`
Moving / morphing on screen	`ease-in-out`
Constant motion (progress, marquee)	`linear`
Default	`ease-out`

Never
ease-in
on UI. It starts slow, delaying the exact moment the user is watching. Reanimated's built-ins are as weak as CSS's — use these:

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

const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1);      // strong ease-out for UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1);  // on-screen movement
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1);    // iOS sheet curve

Duration:

Element	Duration
Press feedback	100–150ms
Toggle, chip, small state change	150–200ms
Sheet, modal, drawer	spring, ~300ms perceived
Screen transition	the platform default — don't override it

Mobile UI animations stay under 300ms, same as web. The platform's own transitions are longer (iOS push is 350ms); match the platform for navigation, beat it everywhere else.

如果涉及手指操作，使用弹簧动画。弹簧动画会在中断时保留速度；时序曲线会重新开始。其他所有场景使用时序动画。

Reanimated的弹簧动画直接支持苹果的两个设计参数——使用以下格式，而非mass/stiffness/damping：

交互场景	配置
默认归位，无过冲	`{ duration: 400, dampingRatio: 1 }`
重新定位/拖拽后弹回	`{ duration: 400, dampingRatio: 0.8, velocity }`
弹窗、抽屉	`{ duration: 300, dampingRatio: 0.8, velocity }`
不能越过硬边界	添加 `overshootClamping: true`

仅当手势带有动量时才使用弹跳效果。淡入的菜单添加过冲效果会显得怪异；而你轻弹的卡片添加过冲效果则很自然。

缓动函数，适用于所有无手指操作的场景：

场景	缓动函数
进入或退出	`ease-out`
屏幕内移动/变形	`ease-in-out`
匀速运动（进度条、跑马灯）	`linear`
默认	`ease-out`

绝不要在UI元素上使用
ease-in
。它开始缓慢，会延迟用户关注的关键时刻。Reanimated的内置缓动函数和CSS的一样弱——使用以下自定义函数：

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

const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1);      // strong ease-out for UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1);  // on-screen movement
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1);    // iOS sheet curve

时长：

元素	时长
按压反馈	100–150ms
开关、芯片、小型状态变化	150–200ms
弹窗、模态框、抽屉	弹簧动画，感知时长约300ms
屏幕过渡	使用平台默认时长——不要覆盖

移动端UI动画时长保持在300ms以内，与网页一致。平台自身的过渡时长更长（iOS推送动画为350ms）；导航动画匹配平台，其他场景则要快于平台。

6. Keep it off the JS thread

6. 让动画远离JS线程

This is the mobile-specific craft, and it's where most React Native motion dies.

Never
setState
from a gesture or scroll handler. One React render per frame is the single biggest cause of jank in RN apps. Shared value →
```
useAnimatedStyle
```
, and React never re-renders at all.
Never schedule back to the RN runtime inside
onUpdate
or a scroll handler.
```
scheduleOnRN(fn, ...args)
```
from
```
react-native-worklets
```
— the Reanimated 4 replacement for the deprecated
```
runOnJS(fn)(...args)
```
— queues an RN-runtime call, and in
```
onUpdate
```
that's 60–120× per second. It belongs in
```
onEnd
```
, or in a
```
useAnimatedReaction
```
that fires when a value crosses a threshold.
Never read a shared value during render (
```
translateY.get()
```
in JSX). It's a snapshot that never updates and it silently desyncs. Never write one during render either — it fires mid-reconciliation, and a re-render you didn't cause replays the write. Touch shared values only in worklets, handlers, and effects.
Use
.get()
/
.set()
, not
.value
. Same API, but direct
```
.value
```
access is the form the React Compiler can't see through — the Reanimated docs call
```
get
```
/
```
set
```
the compiler-safe way.
```
set
```
also takes a functional update:
```
sv.set((v) => v + 1)
```
.
Functions called from a worklet need
'worklet'
as their first line, or they throw at runtime on device while working fine in the debugger.

这是移动端特有的开发技巧，也是大多数React Native动效失效的原因。

绝不要从手势或滚动处理器中调用
setState
。每帧触发一次React渲染是RN应用卡顿的最大原因。使用共享值 →
```
useAnimatedStyle
```
，React完全不会重新渲染。
绝不要在
onUpdate
或滚动处理器中调度回RN运行时。
```
react-native-worklets
```
中的
```
scheduleOnRN(fn, ...args)
```
——Reanimated 4中替代已废弃的
```
runOnJS(fn)(...args)
```
的方法——会将RN运行时调用加入队列，而在
```
onUpdate
```
中这会每秒触发60–120次。应该放在
```
onEnd
```
中，或放在当值超过阈值时触发的
```
useAnimatedReaction
```
中。
绝不要在渲染期间读取共享值（比如在JSX中调用
```
translateY.get()
```
）。这是一个不会更新的快照，会导致静默不同步。也不要在渲染期间写入共享值——它会在调和过程中触发，而你未触发的重新渲染会重复写入操作。仅在worklets、处理器和副作用中操作共享值。
使用
.get()
/
.set()
，而非
.value
。API相同，但直接访问
```
.value
```
是React编译器无法识别的形式——Reanimated文档称
```
get
```
/
```
set
```
是编译器安全的方式。
```
set
```
还支持函数式更新：
```
sv.set((v) => v + 1)
```
。
从worklet中调用的函数需要将
'worklet'
作为第一行，否则在设备运行时会抛出错误，但在调试器中正常工作。

7. Press, not hover

7. 按压而非悬停

Every hover affordance from the web has to be redesigned, not ported.

Feedback on press-in, commit on press-out. Waiting for the tap to complete before showing anything feels dead — this is the latency the user actually perceives.
scale: 0.97
in 100–150ms on any pressable,
```
Pressable
```
+ a CSS transition.
```
scale
```
takes the label and icons with it, which is what makes it read as physical.
44×44pt minimum touch target (48dp Android). If the visual is smaller, add
```
hitSlop
```
— don't grow the visual.
pressRetentionOffset
so a finger drifting a few pixels doesn't cancel a press the user meant.
Android ripple only in a Material-styled app. In a custom-designed app, the same scale on both platforms is more coherent than a ripple on one.

网页中所有依赖悬停的交互提示都必须重新设计，而非直接移植。

按压时提供反馈，松开时执行操作。等待点击完成后再显示任何内容会显得迟钝——这是用户实际感知到的延迟。
任何可按压元素在100–150ms内执行
scale: 0.97
，使用
```
Pressable
```
+ CSS过渡。
```
scale
```
会同时缩放标签和图标，让元素看起来有物理质感。
最小触摸目标为44×44pt（安卓为48dp）。如果视觉元素更小，添加
```
hitSlop
```
——不要放大视觉元素。
设置
pressRetentionOffset
，这样手指漂移几个像素不会取消用户想要执行的按压操作。
仅在Material风格的应用中使用安卓波纹效果。在自定义设计的应用中，两个平台使用相同的缩放效果比仅在安卓使用波纹效果更连贯。

8. Haptics

8. 触觉反馈

Mobile has a sense the web doesn't. Use it sparingly and it becomes the thing that makes the app feel expensive; use it everywhere and users turn it off.

Moment	Call
A value ticks past a step — picker, slider detent, segmented control	`Haptics.selectionAsync()`
Something snaps home, a sheet detent catches, a drag commits	`Haptics.impactAsync(ImpactFeedbackStyle.Light)`
A heavy object lands, a destructive action fires	`Haptics.impactAsync(ImpactFeedbackStyle.Medium)`
Operation succeeded or failed	`Haptics.notificationAsync(NotificationFeedbackType.Success / Error)`

Three rules, and they're absolute:

Same frame as the visual. A haptic that lags its animation reads as a glitch, not as feedback. Fire it at the causal moment — the detent catching — not when the animation finishes.
One per user action. Never on scroll, never per frame, never on an entrance animation the user didn't cause.
Never the only feedback. Haptics are off system-wide for many users, and silent on most Android hardware. The visual has to stand alone.

From a worklet, haptics must be scheduled back to the RN runtime:

scheduleOnRN(Haptics.selectionAsync)

移动端拥有网页没有的感官体验。谨慎使用会让应用显得高端；滥用则会让用户关闭该功能。

场景	调用方法
值步进变化——选择器、滑块定位、分段控件	`Haptics.selectionAsync()`
元素归位、弹窗定位、拖拽确认	`Haptics.impactAsync(ImpactFeedbackStyle.Light)`
重型元素落地、破坏性操作执行	`Haptics.impactAsync(ImpactFeedbackStyle.Medium)`
操作成功或失败	`Haptics.notificationAsync(NotificationFeedbackType.Success / Error)`

三条绝对规则：

与视觉效果同帧触发。触觉反馈滞后于动画会被视为故障，而非反馈。在因果时刻触发——比如定位完成时——而非动画结束时。
每个用户操作仅触发一次。绝不要在滚动时触发，绝不要每帧触发，绝不要在用户未触发的入场动画中触发。
绝不要仅依赖触觉反馈。许多用户会全局关闭触觉反馈，而且大多数安卓设备没有该功能。视觉反馈必须独立有效。

在worklet中，触觉反馈必须调度回RN运行时：

scheduleOnRN(Haptics.selectionAsync)

。

9. Reduced motion and accessibility

9. 简化动效与无障碍

jsx

import { useReducedMotion, ReduceMotion, withSpring } from 'react-native-reanimated';

const reduced = useReducedMotion();
const y = useSharedValue(reduced ? 0 : SHEET_HEIGHT);

// or let each animation decide
withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });

Reduced motion means fewer and gentler, not zero: keep opacity and color changes that explain a state change, drop translation, scale, parallax and overshoot. Screen transitions become

animation: 'fade'

Text scales.

allowFontScaling

is on by default, so any height you measured at default type size is wrong at 200%. Never animate to a hardcoded height — measure with

onLayout

, or animate a transform instead.

jsx

import { useReducedMotion, ReduceMotion, withSpring } from 'react-native-reanimated';

const reduced = useReducedMotion();
const y = useSharedValue(reduced ? 0 : SHEET_HEIGHT);

// 或让每个动画自行判断
withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });

简化动效意味着更少、更温和，而非完全移除：保留用于解释状态变化的透明度和颜色变化，移除位移、缩放、视差和过冲效果。屏幕过渡改为

animation: 'fade'

。

文本会缩放。

allowFontScaling

默认开启，因此你在默认字号下测量的任何高度在200%字号下都是错误的。绝不要动画到硬编码高度——使用

onLayout

测量，或改为动画transform。

Setup that silently breaks motion

会静默破坏动效的配置

Check these first when "the animation just doesn't run":

Install through Expo so versions match the SDK:
```
npx expo install react-native-reanimated react-native-worklets
```
. In an Expo project,
```
babel-preset-expo
```
configures the worklets Babel plugin automatically — no
```
babel.config.js
```
step. Only a bare RN project without that preset adds the plugin manually, and there it must be last in the list. A missing or misplaced plugin doesn't silently fall back anymore — it throws
```
Failed to create a worklet
```
at runtime.
```
GestureHandlerRootView
```
must wrap the app, or gestures do nothing with no error.
Reanimated 4 requires the New Architecture.
Expo Go is not a performance environment. Judge feel in a release build; a dev build's JS thread is slow enough to hide exactly the problems you're looking for.

当「动画无法运行」时，首先检查以下内容：

通过Expo安装以匹配SDK版本：
```
npx expo install react-native-reanimated react-native-worklets
```
。在Expo项目中，
```
babel-preset-expo
```
会自动配置worklets Babel插件——无需修改
```
babel.config.js
```
。只有不使用该预设的纯RN项目才需要手动添加插件，且必须放在列表最后。缺失或位置错误的插件不会静默降级——会在运行时抛出
```
Failed to create a worklet
```
错误。
```
GestureHandlerRootView
```
必须包裹整个应用，否则手势无法工作且无错误提示。
Reanimated 4需要新架构。
Expo Go不是性能测试环境。在发布版本中判断动画体验；开发版本的JS线程足够慢，会隐藏你要排查的问题。

120fps

On ProMotion iPhones, third-party animations are capped at 60fps unless

CADisableMinimumFrameDurationOnPhone

is set. Recent Expo SDKs set it by default — confirm it's there, and add it if not:

json

{ "expo": { "ios": { "infoPlist": { "CADisableMinimumFrameDurationOnPhone": true } } } }

Then the frame budget is 8ms, not 16. This is also why a UI-thread animation matters more on mobile than it does on web.

在ProMotion iPhone上，第三方动画默认被限制在60fps，除非设置

CADisableMinimumFrameDurationOnPhone

。最新的Expo SDK默认会设置该值——确认它已存在，否则添加：

json

{ "expo": { "ios": { "infoPlist": { "CADisableMinimumFrameDurationOnPhone": true } } } }

此时每帧预算为8ms，而非16ms。这也是为什么移动端UI线程动画比网页更重要的原因。

Recipes

方案示例

For ready-to-build implementations — press feedback, drag-to-dismiss sheet, swipe-to-delete, collapsing header, list entrances, keyboard-synced UI, tab indicator, screen transitions — see RECIPES.md. Load it whenever the request matches one; start from the recipe rather than from a blank file.

如需现成的实现代码——按压反馈、拖拽关闭弹窗、滑动删除、折叠头部、列表入场、同步键盘的UI、标签指示器、屏幕过渡——请查看RECIPES.md。当需求匹配时直接使用；基于方案开发而非从零开始。

Never Ship

绝不要交付的内容

Never	Instead
`PanResponder`	`Gesture.Pan()` from gesture-handler
`setState` in a gesture or scroll handler	shared value + `useAnimatedStyle`
`runOnJS` (deprecated in Reanimated 4)	`scheduleOnRN` from `react-native-worklets`
`scheduleOnRN` per frame	`onEnd` , or `useAnimatedReaction` at a threshold
Reading or writing a shared value during render	`.get()` / `.set()` in worklets, handlers, effects
Core `Animated` for anything a finger touches	Reanimated
Animating `height` / `width` / `margin` / `flex` / `top`	`transform` + `opacity` (absolute, childless elements exempt)
Animating `BlurView` intensity or Android `elevation`	crossfade a static layer
`entering` on a virtualized list row	animate the container, or `itemLayoutAnimation`
A screen transition rebuilt in JS	native stack `animation`
Sliding between tabs	`animation: 'none'`
`Easing.in(...)` on a UI element	`Easing.bezier(0.23, 1, 0.32, 1)`
`scale(0)` entrance	`scale(0.95)` + `opacity: 0`
Distance-only dismissal threshold	velocity or distance — a flick is enough
Hard stop at a boundary	rubber-band resistance
A haptic per frame, or as the only feedback	one per commit, always paired with a visual
Judging feel in Expo Go or the simulator	release build, slowest supported device

绝不要做	替代方案
`PanResponder`	使用gesture-handler的 `Gesture.Pan()`
在手势或滚动处理器中调用 `setState`	共享值 + `useAnimatedStyle`
`runOnJS` （Reanimated 4中已废弃）	使用 `react-native-worklets` 的 `scheduleOnRN`
每帧调用 `scheduleOnRN`	放在 `onEnd` 中，或在阈值处使用 `useAnimatedReaction`
在渲染期间读取或写入共享值	在worklets、处理器、副作用中使用 `.get()` / `.set()`
为手指触摸的元素使用核心 `Animated`	使用Reanimated
对 `height` / `width` / `margin` / `flex` / `top` 做动画	使用 `transform` + `opacity` （无子女的绝对定位元素除外）
对 `BlurView` 强度或安卓 `elevation` 做动画	交叉淡入静态图层
在虚拟化列表行上使用 `entering`	动画容器，或使用 `itemLayoutAnimation`
用JS重新实现屏幕过渡	使用原生栈 `animation`
标签间滑动切换	设置 `animation: 'none'`
在UI元素上使用 `Easing.in(...)`	使用 `Easing.bezier(0.23, 1, 0.32, 1)`
使用 `scale(0)` 入场	使用 `scale(0.95)` + `opacity: 0`
仅基于距离的关闭阈值	速度或距离——轻弹即可触发
在边界处硬停止	使用橡皮筋阻力效果
每帧触发触觉反馈，或仅依赖触觉反馈	每个操作触发一次，始终搭配视觉反馈
在Expo Go或模拟器中判断动画体验	在发布版本、支持的最慢设备中测试

Output

输出要求

Write the code. Then, in at most a few lines:

The gate result — frequency tier and named purpose. Say what you rejected and why.
The ingredients — tool, properties, spring or curve + duration, thread.
What to feel-check on device — gestures, velocity handoff and haptic timing cannot be judged from code. Name what to try: flick it, interrupt it mid-flight, reverse it, run it on the slowest Android you have.

The code is the deliverable. Don't pad it into a report.

编写代码。然后用最多几句话说明：

判断结果——使用频率层级和明确目的。说明你拒绝了什么以及原因。
实现要素——工具、属性、弹簧/曲线+时长、线程。
需在设备上验证的体验——手势、速度衔接和触觉时机无法通过代码判断。说明要测试的内容：轻弹、中途中断、反向操作、在最慢的安卓设备上运行。

代码是交付物。不要将其填充成报告。

Tone

语气

Opinionated and brief. When the honest answer is "this shouldn't animate," or "this needs a real device before I can tell you if it's right," give it.