在 Expo/React Native 里做动画与手势时…

为 Expo/React Native 应用加动画、手势、sheet、屏幕转场、按压反馈或触感，或修复真机上卡顿掉帧的动效时使用。

适用场景

解决思路

1. 按频率过第一道闸门决定是否动画：每天 100+ 次的操作（tab 切换、键盘开合、滚动、设置里的开关）不加动画，用平台默认或什么都不做；每天数十次的操作（按压反馈、列表导航、行选择）只做几乎察觉不到的动画，150ms 以内，或不做；偶尔发生的（sheet、modal、toast、onboarding 步骤）用标准动画；罕见/首次发生的（成功状态、空状态插画、庆祝）才把 delight 预算花在这里。
2. Tab 切换绝不滑动：tabs 是同级而非层级，滑动会暗示并不存在的深度，直接用 `animation: 'none'`。
3. 请求没过频率闸门就直接说明不该动画，不要写代码。
4. 动手前用一个词命名动画目的：feedback、spatial consistency、state indication、防止突兀变化、explanation，或 delight（仅罕见档）；命名不出来就不要做。
5. 按「最便宜且够用」的顺序选工具，命中即停：状态驱动且没有手势的变化（按压、开关、颜色、值翻转）用 Reanimated CSS transition（style 里的 `transitionProperty`）。
6. 循环、多阶段、挂载即播放且没有状态变化，用 Reanimated CSS animation（`animationName` keyframes）。
7. 元素挂载/卸载或列表重排，用 layout animations（`entering` / `exiting` / `itemLayoutAnimation`）。
8. 任何手指触碰的值，或由滚动派生的值，用 `useSharedValue` + `Gesture` + `useAnimatedStyle`。
9. 屏幕到屏幕的转场用 Expo Router 的 native stack options，绝不手写。
10. 作为独立屏幕的底部 sheet 用 `presentation: 'formSheet'`，它是真正的 UISheetPresentationController，免费且正确。
11. Tab bar 用 `NativeTabs`（来自 `expo-router/unstable-native-tabs`），平台真实 tab bar 的行为和转场都自带。
12. 上下文菜单、长按预览用 `Link.Menu` / `Link.Preview`（Expo Router，仅 iOS），绝不用 JS 重建。
13. 折叠成大标题的 header 用 native stack 的 `headerLargeTitleEnabled`（仅 iOS；`headerLargeTitle` 已废弃），不要用 scroll worklet。
14. 下拉刷新用 `RefreshControl`，只有它是标志性交互时才手写（见阈值配方）。
15. 跟随键盘的 UI 用 `react-native-keyboard-controller`，拿到键盘真实位置、逐帧、在 UI 线程（需在根节点放 `KeyboardProvider`）。
16. 矢量插画、庆祝、空状态用 Lottie，只用于插画，绝不用于 UI 状态。
17. 超大动画场景、自由绘制用 `@shopify/react-native-skia`，当视图层级本身成为瓶颈时才用。
18. 只在值是连续或可中断时才用 shared value：按压缩放是 CSS transition，拖拽才是 shared value；用 worklet 做两态切换，等于为一次淡入装一整个动画库。
19. 依赖统一用 `npx expo install <package>` 安装以匹配项目 SDK 版本，普通 `npm install` 做不到；动画装 `react-native-reanimated` + `react-native-worklets`，手势装 `react-native-gesture-handler`，导航/sheet/原生 tab/菜单装 `expo-router`，触感装 `expo-haptics`，键盘跟随装 `react-native-keyboard-controller`，插画/庆祝装 `lottie-react-native`，超大场景与自绘装 `@shopify/react-native-skia`。
20. 只动 `transform` 和 `opacity`（免费）；`width`、`height`、`margin`、`padding`、`flex`、`top`、`left`、`gap` 会让该节点及其兄弟节点每帧重跑 Yoga。
21. 唯一例外是「绝对定位且无子元素」的元素（tab pill、进度条填充）：它脱离文档流，动 `width` 还能保住圆角，而 `scaleX` 会把圆角拉花。
22. 绝不用 `scale(0)` 入场，从 `scale(0.9–0.97)` + `opacity: 0` 开始，现实里没有东西从「无」里出现。
23. `transform` 是数组且顺序有意义：`[{ translateY }, { scale }]` 是先移动后缩放；反过来 translate 也会被缩放；除非就是要这个乘法，否则把 translate 放前面。
24. Android 阴影是 `elevation`，动 elevation 会每帧重渲染阴影；改为对一个预先带阴影的层动 opacity。
25. 绝不动 `BlurView` 的 intensity（Android 每帧重渲染模糊）；改为对静态 `BlurView` 的 opacity 做交叉淡入。
26. 百分比可用在 `translate` 且相对元素自身尺寸：`translateY('100%')` 按自身高度移动 sheet，与内容多少无关。
27. 有手指参与就用 spring（能带着速度穿越中断），其余一律用 timing，因为 timing 曲线中断后只能重启。
28. Reanimated 的 spring 直接用 Apple 的两个设计参数（duration + dampingRatio），不要用 mass/stiffness/damping：默认落定无过冲用 `{ duration: 400, dampingRatio: 1 }`；拖动后重新定位/回弹用 `{ duration: 400, dampingRatio: 0.8, velocity }`；sheet、drawer 用 `{ duration: 300, dampingRatio: 0.8, velocity }`；不能越过硬边界时加 `overshootClamping: true`。
29. 只有手势带了动量才回弹：菜单淡入时过冲是错的，甩出去的卡片过冲才是对的。
30. 没有手指参与时的 easing：进入/退出用 `ease-out`，屏幕上移动/形变用 `ease-in-out`，恒定运动（进度、跑马灯）用 `linear`，默认 `ease-out`。
31. 绝不在 UI 上用 `ease-in`：它起步慢，恰好拖住用户正在盯着看的那一刻。
32. 用强曲线替代 Reanimated 内置的弱曲线：`transitionTimingFunction` / `animationTimingFunction` 用 `cubicBezier(0.23, 1, 0.32, 1)`；`withTiming` / `.easing(...)` 用 `Easing.bezier(0.23, 1, 0.32, 1)`（UI 强 ease-out）、`Easing.bezier(0.77, 0, 0.175, 1)`（屏幕内移动）、`Easing.bezier(0.32, 0.72, 0, 1)`（iOS sheet 曲线）。
33. Reanimated 4.1.1 和 4.5.1 会拒绝裸 `'cubic-bezier(...)'` 字符串：CSS transitions/animations 用 `cubicBezier(...)`，`withTiming` 和 `.easing(...)` 用 `Easing.bezier(...)`。
34. 时长：按压反馈 100–150ms；toggle、chip、小状态变化 150–200ms；sheet/modal/drawer 用 spring、感知约 300ms；屏幕转场用平台默认、不要覆盖；移动端 UI 动画和 Web 一样保持 300ms 以内。
35. 绝不在手势或滚动处理器里 `setState`：每帧一次 React 渲染是 RN 卡顿的最大单一原因；改用 shared value → `useAnimatedStyle`，React 完全不重渲染。
36. 绝不在 `onUpdate` 或滚动处理器里调度回 RN runtime：`scheduleOnRN(fn, ...args)`（来自 `react-native-worklets`，Reanimated 4 中替代已废弃的 `runOnJS`）放在 `onUpdate` 里等于每秒 60–120 次调用；它只应出现在 `onEnd`，或 `useAnimatedReaction` 中值越过阈值的时刻。
37. 绝不在 render 期间读 shared value（如 JSX 里的 `translateY.get()`）：那是一个永不更新的快照，会静默失同步；也绝不在 render 期间写，它会在 reconciliation 中途触发，且一次并非由你引起的重渲染会重放这次写入；shared value 只在 worklet、handler 和 effect 里碰。
38. 用 `.get()` / `.set()` 而不是 `.value`：同一套 API，但 `.value` 是 React Compiler 看不穿的写法；`set` 还支持函数式更新 `sv.set((v) => v + 1)`。
39. 从 worklet 里调用的函数第一行必须写 `'worklet'`，否则在设备上运行时抛错（而在 debugger 里可能一切正常）。
40. Press 而非 hover：press-in 就给反馈、press-out 才提交；等到点击完成才给反馈会显得迟钝，而这正是用户实际感知到的延迟。
41. 任何按钮类的可按元素用 `Pressable` + CSS transition，在 100–150ms 内 `scale: 0.97`（scale 会带上标签和图标一起动，这才读得出物理感）；整行列表是例外，改为高亮背景，因为缩放整行会像整块屏幕被压扁。
42. 触摸目标最小 44×44pt（Android 48dp）；视觉更小就加 `hitSlop`，不要放大视觉；用 `pressRetentionOffset` 让手指偏移几个像素不会取消用户本意的按压。
43. Android ripple 只在 Material 风格 app 里用；自定义设计的 app 里，两端用同一个 scale 比单端 ripple 更统一。
44. Haptics 按场景调用：值越过一格（picker、slider detent、segmented control）用 `Haptics.selectionAsync()`；吸附归位、sheet detent 卡住、拖拽提交用 `Haptics.impactAsync(ImpactFeedbackStyle.Light)`；重物落地、破坏性操作触发用 `ImpactFeedbackStyle.Medium`；操作成功或失败用 `Haptics.notificationAsync(NotificationFeedbackType.Success / Error)`。
45. Haptics 必须与视觉同帧、在因果时刻触发（detent 卡住那一刻），而不是动画结束时；每个用户动作只一次，绝不随滚动、每帧、或非用户引起的入场动画触发；绝不作为唯一反馈（很多用户系统级关闭触感，多数 Android 硬件无声），视觉必须能独立成立。
46. 在 worklet 里触发 haptics 必须调度回 RN runtime：`scheduleOnRN(Haptics.selectionAsync)`。
47. Reduced motion 随动画一起交付：用 `useReducedMotion()` 决定初始值，或用 `withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System })` 让每个动画自行决定。
48. Reduced motion 的意思是「更少更温和」而不是零：保留解释状态变化的 opacity 和颜色变化，去掉平移、缩放、视差和过冲；屏幕转场改为 `animation: 'fade'`。
49. 文本会缩放（`allowFontScaling` 默认开启），默认字号下量到的高度在 200% 字号时是错的：绝不动画到硬编码高度，用 `onLayout` 测量，或改为动 transform。
50. 排查「动画根本不跑」时先查 setup：用 `npx expo install react-native-reanimated react-native-worklets` 安装以匹配 SDK；Expo 项目由 `babel-preset-expo` 自动配置 worklets Babel 插件，不需要动 `babel.config.js`；只有不带该 preset 的 bare RN 项目才手动加插件，且必须排在列表最后（插件缺失或位置错误不再静默降级，会在运行时抛 `Failed to create a worklet`）。
51. `GestureHandlerRootView` 必须包裹整个 app，否则手势什么都不做且不报错。
52. Reanimated 4 需要 New Architecture。
53. Expo Go 不是性能环境：手感要在 release 构建上判断，dev build 的 JS 线程慢到正好会掩盖你正在找的那些问题。
54. 在 ProMotion iPhone 上，第三方动画默认被限制在 60fps，除非设置 `CADisableMinimumFrameDurationOnPhone`：确认 `expo.ios.infoPlist` 里已有该项，没有就加上；此后帧预算是 8ms 而不是 16ms。
55. 请求匹配现成配方时先加载 `RECIPES.md`，从配方（press feedback、drag-to-dismiss sheet、swipe-to-delete、collapsing header、list entrances、keyboard-synced UI、tab indicator、screen transitions）开始，而不是从空文件开始。
56. 禁止与替代：手势处理用 `Gesture.Pan()` 而不是 `PanResponder`；手指触碰的东西用 Reanimated 而不是 core `Animated`；用 `scheduleOnRN` 而不是 Reanimated 4 中已废弃的 `runOnJS`；虚拟化列表行不要用 `entering`（改为动容器或 `itemLayoutAnimation`）；屏幕转场不要用 JS 重建（用 native stack 的 `animation`）；关闭阈值不要只看距离（速度或距离任一满足即可，轻轻一甩就够）；边界不要硬停（用 rubber-band 阻力）；不要在 Expo Go 或模拟器里判断手感（在 release 构建、你支持的最慢设备上判断）。
57. 交付时先写代码，再用最多几行说明：闸门结果（频率档位和命名的目的，说明否决了什么以及为什么）、用到的材料（工具、属性、spring 或曲线加时长、所在线程）、需要在真机上验证手感的内容（甩一下、飞在半途时打断、反向操作、在你手上最慢的 Android 上跑），因为手势、速度交接和触感时机无法从代码判断。
58. 遇到本技能里的错误、误导或过时信息时用 `npx --yes submit-expo-feedback@latest --category skills --subject "expo-animation" "<actionable feedback>"` 提交反馈；仅在确有具体可操作内容时提交，并带上尽可能多的相关上下文；如果 AI agent 反复失败或用户不得不接手，改用 expo-skill-feedback 技能的 eval-candidate 流程，而不是重复上面的命令。

适用边界 · 注意事项

• 做 Web 动画时不适用，应改用 `animate` 技能。
• 该交互高频发生（每天 100+ 次，如 tab 切换、键盘开合、滚动、设置开关）时不适用——正确答案是不加动画。
• 无法在真机 release 构建（你支持的最慢设备）上验证手感时不适用：模拟器、Expo Go 和 dev build 都不能作为判定依据。