Communitygithub.com

Asymmetric-al/core(Expo / React Native 动画构建技能)

仅用于在 Expo 和 React Native 中构建动画,使用 Reanimated、Gesture Handler、Expo Router 和 expo-haptics。当目标运行时是 Expo 或 React Native 应用时使用。不适用于 Core Next.js 网页动效(请使用 `animate`)。仅在明确调用时触发,不会自行激活。

core(Expo / React Native 动画构建技能) 是什么?

这是一个专门针对 React Native / Expo 平台构建高性能移动动画的开发技能。它要求开发者遵循严格的构建流程,包括判断动画必要性、明确动画目的、选择最轻量的工具、合理选择动画属性、正确使用时序或弹簧动画,并确保动画运行在 UI 线程上以避免卡顿。技能强调移动端动画的三个核心变化:无悬停状态、双运行时(React Native 运行时与 UI 运行时)、手指触摸为核心输入。它支持 Reanimated、Gesture Handler、Expo Router、expo-haptics、react-native-keyboard-controller 等库,并提供了详细的配置表(如弹簧参数、缓动曲线、持续时间)以及针对不同场景(如标签切换、表单面板、按压反馈)的推荐实现方式。技能还包含严格的代码审查清单,防止动画在错误线程上运行或动画不该动的内容。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Asymmetric-al/core/tree/HEAD/.agents/skills/animate-expo

在你喜欢的 AI 中提问

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

文档

在 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 网页动效加载此技能。

工作流程

  1. 在应用 Reanimated 方案前确认请求是原生/Expo 的。
  2. 对于 Core 的 Next.js 表面,停止并加载 animate 和 anim。

检查清单

  • 目标运行时是 Expo/React Native,而非 Core 的 App Router 应用。
  • 网页动效仍遵循 Core 的 token 和 Base UI。

一个针对 React Native 的构建技能。它将一个动效需求转化为能在真实设备上通过严格审查的实现——而不是在模拟器上,也不是在旗舰手机的开发模式下。

移动端改变了动画的三个要素,本技能中的所有内容都源于此:

  1. 没有悬浮态。 网页上所有放在悬浮态中的交互都必须存在于按压、位置或留白中。
  2. 有两个运行时。 Worklets(Reanimated 4)明确了这一点:一个是 React Native 运行时,React 在此渲染,你的应用逻辑在此运行;另一个是 UI 运行时,worklets 在此每帧执行(另外还有可选的 worker 运行时用于后台工作)。一个触及 RN 运行时的动画,在应用做其他任何事时都会卡顿。整个技巧在于保持动效在 UI 运行时上。
  3. 用户的手指就在元素上。 手势是主要的输入方式,因此可中断性和速度传递不是锦上添花——而是基线要求。

操作姿态

你是一位资深移动端工程师,亲自构建动画。做出决定,用一句话陈述理由,然后写代码。永远不要把动效选项当作菜单来呈现。

两种失败模式,第一种更严重:

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

硬性规则

  1. 按顺序执行步骤。 步骤 1 和 2 是其他一切的门控。
  2. 使用 Reanimated,而不是核心的 Animated。 核心 Animated 无法在不跨桥的情况下由手势驱动,而且 useNativeDriver 除了 transform 和 opacity 外拒绝其他任何东西。Reanimated worklets 在 UI 线程上运行,在 JS 忙碌时仍能继续运行。
  3. 没有近似值。 曲线和弹簧配置来自下面的表格。
  4. 减少动效与动画一同交付,而不是作为后续步骤。
  5. 感觉必须在你支持的最慢设备上的发布构建中进行判断。 其他任何方式都不算验证通过。

构建顺序

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——仅当这是一个标志性交互时再手写(参见阈值配方)
跟随键盘的 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 在前。
  • 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())。它是一个永远不会更新的快照,而且它静默地

...

[内容已截断]

Individual skills in this repo

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

Asymmetric-al/core

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations. Only runs when explicitly invoked; it does not trigger on its own.

Asymmetric-al/core

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

Asymmetric-al/core

Inspect a Core UI or code surface for a small number of justified motion opportunities and explicitly identify what should remain static. Use when asked what should animate, where motion would improve feedback or comprehension, how to make an interface feel more alive without over-animating it, or whether a proposed animation is worth adding. Read-only; do not use to review or fix existing motion code or to implement animations.

Asymmetric-al/core

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

Asymmetric-al/core

Implement smooth, accessible animations with motion/react (Framer Motion) in React. Use when adding animations, gestures, or layout transitions with motion, AnimatePresence, useScroll, and related APIs. Requires a 'use client' boundary; not for strictly server-rendered components or when no animation is needed.

Asymmetric-al/core

Best practices for Remotion - Video creation in React

Asymmetric-al/core

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

相关技能