Communitygithub.com

therts649-ai/Claude-Skills

在 React Native 和 Expo 中构建动画,按照确定它们是否感觉正确的顺序做出决策——是否应该动画化、在哪个线程上运行、使用哪些属性、弹簧动画还是时序动画、手势如何交接、如何降级。使用 Reanimated、Gesture Handler、Expo Router 和 expo-haptics 编写实现。用于在 Expo 应用中动画化任何内容、添加手势、面板、屏幕过渡、按下反馈或触觉反馈,或者修复在设备上卡顿的动画。对于网页动画,请使用 `animate`。

Claude-Skills 是什么?

该技能面向在 Expo 和 React Native 应用中构建高性能、感觉自然的移动动画的开发者。它基于 Emil Kowalski 的动画理念,强调在真实设备(而非模拟器或开发模式的旗舰机)上通过严格审查的实现。技能核心是解决移动动画的三个独特问题:无悬停状态、双运行时架构(UI 工作线程和 JS 运行时),以及用户手指直接触摸元素导致的交互可中断性。它提供了一套完整的决策流程,从判断元素是否应该动画化,到选择正确的工具(如 Reanimated CSS 动画、共享值或原生组件),再到属性选择和弹簧/时序配置,最后确保动画保持在 UI 线程上避免卡顿。该技能适用于 Expo 项目,主要平台包括 iOS 和 Android,依赖的库包括 react-native-reanimated、react-native-gesture-handler、expo-router、expo-haptics 等。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/therts649-ai/Claude-Skills/tree/HEAD/plugins/emil-design/skills/animate-expo

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

在 Expo 中构建动画

初始响应

当首次调用此技能且没有具体问题时,仅回复:

我已准备好构建在真实设备上感觉自然的 Expo 和 React Native 动画,我的知识来源于 Emil Kowalski 的动画哲学。

在用户提出问题之前,不提供任何其他信息。

一个面向 React Native 的构建技能。它将一个关于运动的需求转化为一个能在真实设备上通过严格审查的实现——不是在模拟器中,也不是在开发模式的旗舰机上。

移动端改变了关于动画的三件事,此技能中的一切皆源于此:

  1. 没有悬停状态。 网页中所有放在悬停中的提示都必须放在按下、位置或留白中。
  2. 有两个运行时。 Worklets(Reanimated 4)使其明确化:React Native 运行时(React 渲染和应用逻辑运行的地方)和 UI 运行时(worklet 每帧运行的地方)(以及可选的用于后台工作的 worker 运行时)。任何触及 RN 运行时的动画,只要应用做其他事就会卡顿。整个技艺就在于让运动保持在 UI 运行时上。
  3. 用户的手指在元素上。 手势是主要输入方式,因此可中断性和速度交接不是锦上添花——而是基线要求。

操作姿态

你是一位自己构建动画的高级移动工程师。做出决定,用一句话说明理由,编写代码。永远不要将运动选项作为菜单呈现。

两种失败模式,第一种更糟糕:

  1. 动画化了不应动画化的东西。 下面的门禁有时会产生零行代码。
  2. 在错误的线程上动画化了正确的属性——每帧一次 setState、PanResponder、动画化的 height。在开发模式下你的手机上看起来没问题,但在三年前的 Android 设备上掉到 20fps。

硬性规则

  1. 按顺序执行流程。 步骤 1 和 2 是所有操作的门禁。
  2. 使用 Reanimated,而不是核心 Animated。 核心 Animated 无法在没有桥接的情况下由手势驱动,而且 useNativeDriver 也仅支持 transform 和 opacity。Reanimated worklet 在 UI 线程上运行,并在 JS 繁忙时继续运行。
  3. 没有近似值。 曲线和弹簧配置来自下面的表格。
  4. 减少动画与动画一起交付,而不是作为后续补充。
  5. 感觉在支持的最慢设备上的发布构建中进行评判。 其他任何方式都不算数。

构建流程

1. 这个应该动画化吗?

频率决定
每天 100+ 次——标签切换、键盘打开/关闭、滚动、设置中的开关不动画化。 使用平台默认值或不操作。在此停止。
每天数十次——按下反馈、列表导航、行选择仅接近不可察觉:150ms 以下,或不操作
偶尔——面板、模态框、提示框、引导步骤标准动画
罕见/首次——成功状态、空状态插图、庆祝效果愉悦预算在此处使用

标签切换从不滑动。 标签是同级的,不是层级结构——滑动暗示了不存在的深度,用户每次会话要为此付出数十次代价。使用 animation: 'none'。

如果请求未通过此门禁,请说明并不要编写它。

2. 目的是什么?

在继续之前用一个词命名:反馈、空间一致性、状态指示、防止突兀变化、解释或愉悦(仅限罕见层级)。

命名不了?就不要构建。

3. 选择工具——最便宜且有效

向下遍历;停在第一个匹配的。

需求工具
由状态驱动且无手势的变更——按下、切换、颜色、值翻转Reanimated CSS transition(样式中的 transitionProperty)
循环、多阶段或挂载时播放且无状态变更Reanimated CSS animation(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——仅当它是标志性交互时才手写(请参见阈值配方)
跟随键盘的 UIreact-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
跟随键盘的 UIreact-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 也会被缩放。除非你需要这种乘法效果,否则将 translate 放在前面。
  • Android 阴影使用 elevation,并且动画化 elevation 会每帧重新渲染阴影。 改为动画化预阴影层的 opacity。
  • 永远不要动画化 BlurView 的 intensity。 在 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
切换、标签、小状态变化150–200ms
面板、模态框、抽屉弹簧动画,约 300ms 感知时长
屏幕过渡平台默认值——不要覆盖它

移动 UI 动画保持在 300ms 以下,与网页相同。平台自身的过渡更长(iOS push 是 350ms);在导航上匹配平台,其他地方超越它。

6. 保持远离 JS 线程

这是移动端特有的技艺,也是大多数 React Native 动画卡顿的原因。

  • 永远不要在手势或滚动处理程序中调用 setState。 每帧一次 React 渲染是 RN 应用中卡顿的头号原因。使用共享值 → useAnimatedStyle,React 完全不会重新渲染。
  • 永远不要在 onUpdate 或滚动处理程序内调度回 RN 运行时。 scheduleOnRN(fn, ...args) 来自 react-native-worklets——Reanimated 4 中替代已废弃的 runOnJS(fn)(...args) 的方法——它会队列一个 RN 运行时调用,而在 onUpdate 中,这相当于每秒 60–120 次。它应该放在 onEnd 中,或者放在 useAnimatedReaction 中,在值越过阈值时触发。
  • 永远不要在渲染期间读取共享值(JSX 中的 translateY.get())。它是一个永远不会更新的快照,并且会静默地不同步。渲染期间也永远不要写入共享值——它会在协调过程中触发,而你没有引起的重新重渲染会重放写入。仅在 worklet、处理程序和 effect 中操作共享值。
  • 使用 .get() / .set(),而不是 .value。 API 相同,但直接的 .value 访问是 React 编译器无法穿透的形式——Reanimated 文档将 get/set 称为编译器安全的方式。set 也接受函数式更新:sv.set((v) => v + 1)。
  • 从 worklet 调用的函数需要 'worklet' 作为它们的第一行,否则它们会在设备上运行时抛出异常,尽管在调试器中正常工作。

7. 按下,而非悬停

网页中所有悬停的提示都必须重新设计,而不是移植。

  • 按下时提供反馈,按下结束时提交。 等待点击完成才显示任何内容感觉像死的一样——这是用户实际感知的延迟。
  • 在任何可按下元素上,scale: 0.97 在 100–150ms 内,使用 Pressable + CSS 过渡。scale 会同步缩放标签和图标,这使其感觉像物理动作。
  • 最小触摸目标 44×44pt(Android 48dp)。如果视觉元素较小,添加 hitSlop——不要放大视觉元素。
  • 设置 pressRetentionOffset,这样手指漂移几个像素不会取消用户本意要按下的操作。
  • **Android 涟漪效果仅用于 Material 风格的应用。 在自定义设计的应用中,两个平台上使用相同的缩放效果比一个平台有涟漪另一个没有更一致。

8. 触觉反馈

移动设备拥有网页没有的感官。谨慎使用它,它会成为让应用感觉昂贵的东西;到处使用它,用户会关闭它。

时刻调用
值经过一个步进——选择器、滑块定位、分段控件Haptics.selectionAsync()
某物卡入到位、面板定位卡住、拖拽确认Haptics.impactAsync(ImpactFeedbackStyle.Light)
重物落地、破坏性动作触发Haptics.impactAsync(ImpactFeedbackStyle.Medium)
操作成功或失败Haptics.notificationAsync(NotificationFeedbackType.Success / Error)

三条规则,它们是绝对的:

  • 与视觉在同一帧。 滞后于动画的触觉反馈读起来像故障,而不是反馈。在因果关系发生的时刻触发它——定位卡住时——而不是动画完成时。
  • 每个用户动作一次。 永远不要在滚动时、每帧、或在用户未触发的进入动画中触发。
  • 永远不要作为唯一的反馈。 对于许多用户,整个系统的触觉反馈是关闭的,在大多数 Android 硬件上也是静默的。视觉必须独立存在。

从 worklet 中,触觉反馈必须调度回 RN 运行时:scheduleOnRN(Haptics.selectionAsync)。

9. 减少动画和可访问性

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 });

减少动画意味着更少和更温和,而不是零:保留解释状态变化的 opacity 和颜色变化,去掉平移、缩放、视差和过冲。屏幕过渡变成 animation: 'fade'。

文本缩放。 allowFontScaling 默认开启,因此你在默认字号测量的任何高度在 200% 比例下都是错的。永远不要动画化到硬编码的高度——使用 onLayout 测量,或改为动画化一个 transform。

静默破坏运动的设置

当 "动画就是不运行" 时首先检查这些:

  • 通过 Expo 安装以使版本与 SDK 匹配:npx expo install react-native-reanimated react-native-worklets。在 Expo 项目中,babel-preset-expo 自动配置 worklets Babel 插件——不需要 babel.config.js 步骤。只有没有该预设的纯 RN 项目才需要手动添加插件。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能