在 Expo 中构建动画
本仓库 (Asymmetric-al/core)
此技能仅适用于 React Native / Expo 动效。Core 的 Next.js 应用应使用 animate、emil-design-engineering 和 anim。在上游刷新后,在运行 bun run skills:sync 之前协调此覆盖层。
触发条件
- 明确的 Expo 或 React Native 动画、手势、面板或触觉反馈工作。
- 不要为 Core 的 Web 应用(
apps/admin、apps/donor、apps/missionary)或共享的packages/ui网页动效加载此技能。
工作流程
- 在应用 Reanimated 方案前确认请求是原生/Expo 的。
- 对于 Core 的 Next.js 表面,停止并加载
animate和anim。
检查清单
- 目标运行时是 Expo/React Native,而非 Core 的 App Router 应用。
- 网页动效仍遵循 Core 的 token 和 Base UI。
一个针对 React Native 的构建技能。它将一个动效需求转化为能在真实设备上通过严格审查的实现——而不是在模拟器上,也不是在旗舰手机的开发模式下。
移动端改变了动画的三个要素,本技能中的所有内容都源于此:
- 没有悬浮态。 网页上所有放在悬浮态中的交互都必须存在于按压、位置或留白中。
- 有两个运行时。 Worklets(Reanimated 4)明确了这一点:一个是 React Native 运行时,React 在此渲染,你的应用逻辑在此运行;另一个是 UI 运行时,worklets 在此每帧执行(另外还有可选的 worker 运行时用于后台工作)。一个触及 RN 运行时的动画,在应用做其他任何事时都会卡顿。整个技巧在于保持动效在 UI 运行时上。
- 用户的手指就在元素上。 手势是主要的输入方式,因此可中断性和速度传递不是锦上添花——而是基线要求。
操作姿态
你是一位资深移动端工程师,亲自构建动画。做出决定,用一句话陈述理由,然后写代码。永远不要把动效选项当作菜单来呈现。
两种失败模式,第一种更严重:
- 让不该动的东西动起来。 下面的门控有时就是为了产生零行代码。
- 在错误的线程上动画化正确的东西——每帧一个
setState、一个PanResponder、一个动画化的height。在开发模式下你的手机上看起来没问题,但在三年前的 Android 上会掉到 20fps。
硬性规则
- 按顺序执行步骤。 步骤 1 和 2 是其他一切的门控。
- 使用 Reanimated,而不是核心的
Animated。 核心Animated无法在不跨桥的情况下由手势驱动,而且useNativeDriver除了 transform 和 opacity 外拒绝其他任何东西。Reanimated worklets 在 UI 线程上运行,在 JS 忙碌时仍能继续运行。 - 没有近似值。 曲线和弹簧配置来自下面的表格。
- 减少动效与动画一同交付,而不是作为后续步骤。
- 感觉必须在你支持的最慢设备上的发布构建中进行判断。 其他任何方式都不算验证通过。
构建顺序
1. 这个需要动画吗?
| 频率 | 决策 |
|---|---|
| 每天 100+ 次——标签切换、键盘开合、滚动、设置中的开关切换 | 不需要动画。 使用平台默认或什么都不做。在此停止。 |
| 每天几十次——按压反馈、列表导航、行选择 | 仅需近乎不可察觉:低于 150ms,或什么都不做 |
| 偶尔——面板、模态框、Toast、引导步骤 | 标准动画 |
| 罕见 / 首次——成功状态、空状态插图、庆祝动画 | 愉悦预算在此处使用 |
标签切换永远不要滑动。 标签是平级的,而不是层级关系——滑动暗示了不存在的深度,用户每次会话要为此付出几十次的代价。使用 animation: 'none'。
如果请求未通过此门控,请说出来并不要编写它。
2. 目的是什么?
在继续之前用一个词来命名它:反馈、空间一致性、状态指示、防止突兀变化、解释 或 愉悦(仅限罕见层级)。
无法命名?不要构建它。
3. 选择工具——最便宜且能工作的
向下遍历;在第一个符合的地方停止。
| 需求 | 工具 |
|---|---|
| 无手势的状态驱动变化——按压、切换、颜色、值翻转 | 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)——原生菜单和 Peek,绝不在 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. 选择属性
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 }]先移动后缩放;顺序反过来,位移也会被缩放。除非你需要这种乘法效果,否则保持 translate 在前。- Android 阴影使用
elevation,并且动画化 elevation 会每帧重新渲染阴影。 改为动画化一个预阴影图层的 opacity。 - 永远不要动画化
BlurView的强度。 在 Android 上,它每帧会重新渲染模糊效果。改为交叉淡入淡出一个静态BlurView的 opacity。 - 百分比在
translate中有效,并且相对于元素自身的大小——translateY('100%')会根据面板自身的高度移动它,无论其内容如何。
5. 时序或弹簧
如果涉及手指,使用弹簧。 弹簧在中断时传递速度;时序曲线会重新开始。其他所有情况使用时序。
Reanimated 的弹簧直接使用 Apple 的两个设计师参数——使用此形式,而不是质量/刚度/阻尼:
| 交互 | 配置 |
|---|---|
| 默认稳定,无过冲 | { 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); // 用于 UI 的强 ease-out
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // 屏幕上的运动
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // iOS 面板曲线
持续时间:
| 元素 | 持续时间 |
|---|---|
| 按压反馈 | 100–150ms |
| 切换、chip、小的状态变化 | 150–200ms |
| 面板、模态框、抽屉 | spring,约 300ms 感知 |
| 屏幕过渡 | 平台默认——不要覆盖它 |
移动端 UI 动画保持在 300ms 以下,与网页相同。平台自身的过渡更长(iOS push 是 350ms);在导航上匹配平台,在其他所有地方超越它。
6. 保持远离 JS 线程
这是移动端特有的技巧,也是大多数 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())。它是一个永远不会更新的快照,而且它静默地
...
[内容已截断]