React Native Expo动画指南：Reanimated v4与Gesture Handler实战教程

animating-react-native-expo by tristanmanchester/agent-skills

92 周安装量

GitHub

安装命令

npx skills add https://github.com/tristanmanchester/agent-skills --skill animating-react-native-expo

React 移动应用动画

🇨🇳中文介绍

React Native (Expo) 动画 — Reanimated v4 + Gesture Handler

默认选择（除非有特殊原因，否则请选择这些）

简单状态变化（悬停/按下/切换，小的样式变化）：使用 Reanimated CSS 过渡。
挂载/卸载 + 布局变化（列表、手风琴、回流）：使用 Reanimated 布局动画。
交互式 / 逐帧（手势、滚动、物理、拖拽）：使用 共享值 + 工作单元（UI 线程）。

如果现有代码库已使用不同的模式，请保持一致性，仅在必要时迁移。

快速开始

安装 (Expo)

npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler

运行设置检查（可选）：

node {baseDir}/scripts/check-setup.mjs

1) 共享值 + `withTiming`

import { Pressable } from 'react-native';
import Animated, { useSharedValue, useAnimatedStyle, withTiming } from 'react-native-reanimated';

export function FadeInBox() {
  const opacity = useSharedValue(0);

  const style = useAnimatedStyle(() => ({ opacity: opacity.value }));

  return (
    <Pressable onPress={() => (opacity.value = withTiming(opacity.value ? 0 : 1, { duration: 200 }))}>
      <Animated.View style={[{ width: 80, height: 80 }, style]} />
    </Pressable>
  );
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

2) 驱动平移的拖拽手势 (UI 线程)

import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
import { GestureDetector, usePanGesture } from 'react-native-gesture-handler';

export function Draggable() {
  const x = useSharedValue(0);
  const y = useSharedValue(0);

  const pan = usePanGesture({
    onUpdate: (e) => {
      x.value = e.translationX;
      y.value = e.translationY;
    },
    onDeactivate: () => {
      x.value = withSpring(0);
      y.value = withSpring(0);
    },
  });

  const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }, { translateY: y.value }] }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[{ width: 100, height: 100 }, style]} />
    </GestureDetector>
  );
}

3) CSS 样式过渡（最适合“状态变化时的样式变化”）

import Animated from 'react-native-reanimated';

export function ExpandingCard({ expanded }: { expanded: boolean }) {
  return (
    <Animated.View
      style={{
        width: expanded ? 260 : 180,
        transitionProperty: 'width',
        transitionDuration: 220,
      }}
    />
  );
}

工作流程（复制此清单并勾选）

识别驱动源：状态、布局、手势或滚动。
选择基础模式：
- 状态 → CSS 过渡 / CSS 动画
- 布局/挂载 → 进入/退出/布局过渡
- 手势/滚动 → 共享值 + 工作单元
将逐帧工作保持在 UI 线程（工作单元）；避免每帧都更新 React 状态。
如果需要 JS 端副作用（导航、分析、状态设置），通过 scheduleOnRN 调用它。
在真机上验证（Hermes 检查器），而不是“远程 JS 调试”。

共享值是运行时之间的“连接格式”

对于必须在 UI 和 JS 两端读写的数据（数字/字符串/对象），使用 useSharedValue。
使用 useAnimatedStyle 派生样式。
UI 补间动画优先使用 withTiming；物理效果优先使用 withSpring。

UI 线程 vs JS 线程：唯一重要的规则

手势回调和动画样式应保持工作单元化（UI 运行时）。
仅在必要时才桥接到 JS（通过 scheduleOnRN）。

Gesture Handler：每个子树使用一种 API 风格

默认使用 钩子 API（usePanGesture、useTapGesture 等）。
不要嵌套使用不同 API 风格（钩子 vs 构建器）的 GestureDetector。
不要在多个检测器之间重用同一个手势实例。

CSS 过渡 (Reanimated 4)

当样式值因 React 状态/属性改变而需要动画效果时使用。

始终设置 transitionProperty + transitionDuration。
避免使用 transitionProperty: 'all'（性能 + 意外的动画）。
离散属性（例如 flexDirection）无法平滑过渡；请改用布局动画。

当元素进入/退出，或由于条件渲染/回流导致布局变化时使用。

优先使用预设动画（进入/退出、关键帧、布局过渡）。仅当预设无法表达所需运动时，才使用完全自定义的布局动画。

优先使用 Reanimated 滚动处理器/共享值；保持工作单元体量小巧。完整示例请参见：

“无法创建工作单元” / 工作单元未运行

确保为你的环境配置了正确的 Babel 插件。
- Expo：通过 expo install 安装时，由 babel-preset-expo 处理。
- 裸 React Native：Reanimated 4 使用 react-native-worklets/plugin。

手势回调未触发 / 奇怪的冲突

确保应用根组件已用 GestureHandlerRootView 包裹。
不要在检测器之间重用手势；不要在嵌套的检测器中混合使用钩子和构建器 API。

需要从工作单元调用 JS

使用 scheduleOnRN(fn, ...args)。
fn 必须在 JS 作用域中定义（组件体或模块作用域），而不是在工作单元内部创建。

检查是否有大型对象被捕获到工作单元中；应捕获原始值。
避免使用 transitionProperty: 'all'。
不要每帧都设置 React 状态。

捆绑的参考资料（仅在需要时打开）

references/setup-and-compat.md：Expo 与裸项目设置对比，新架构要求，常见不兼容问题。
references/worklets-and-threading.md：UI 运行时，scheduleOnUI/scheduleOnRN，闭包捕获，迁移说明。
references/gestures.md：GestureDetector，钩子 API 模式，组合，注意事项。
references/css-transitions-and-animations.md：Reanimated 4 CSS 过渡/动画快速参考。
references/layout-animations.md：进入/退出/布局过渡及其选择方法。
references/recipes.md：可复制的组件（拖拽、滑动、捏合、类底部表单、滚动效果）。
references/debugging-and-performance.md：诊断工作单元问题，性能分析，常见性能陷阱。

grep -Rni "scheduleOnRN" {baseDir}/references
grep -Rni "transitionProperty" {baseDir}/references
grep -Rni "usePanGesture" {baseDir}/references

🇺🇸English

React Native (Expo) animations — Reanimated v4 + Gesture Handler

Defaults (pick these unless there’s a reason not to)

Simple state change (hover/pressed/toggled, small style changes): use Reanimated CSS Transitions.
Mount/unmount + layout changes (lists, accordions, reflow): use Reanimated Layout Animations.
Interactive / per-frame (gestures, scroll, physics, drag): use Shared Values + worklets (UI thread).

If an existing codebase already uses a different pattern, stay consistent and only migrate when necessary.

Quick start

Install (Expo)

npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler

Run the setup check (optional):

node {baseDir}/scripts/check-setup.mjs

1) Shared value + `withTiming`

import { Pressable } from 'react-native';
import Animated, { useSharedValue, useAnimatedStyle, withTiming } from 'react-native-reanimated';

export function FadeInBox() {
  const opacity = useSharedValue(0);

  const style = useAnimatedStyle(() => ({ opacity: opacity.value }));

  return (
    <Pressable onPress={() => (opacity.value = withTiming(opacity.value ? 0 : 1, { duration: 200 }))}>
      <Animated.View style={[{ width: 80, height: 80 }, style]} />
    </Pressable>
  );
}

2) Pan gesture driving translation (UI thread)

import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
import { GestureDetector, usePanGesture } from 'react-native-gesture-handler';

export function Draggable() {
  const x = useSharedValue(0);
  const y = useSharedValue(0);

  const pan = usePanGesture({
    onUpdate: (e) => {
      x.value = e.translationX;
      y.value = e.translationY;
    },
    onDeactivate: () => {
      x.value = withSpring(0);
      y.value = withSpring(0);
    },
  });

  const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }, { translateY: y.value }] }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[{ width: 100, height: 100 }, style]} />
    </GestureDetector>
  );
}

3) CSS-style transition (best for “style changes when state changes”)

import Animated from 'react-native-reanimated';

export function ExpandingCard({ expanded }: { expanded: boolean }) {
  return (
    <Animated.View
      style={{
        width: expanded ? 260 : 180,
        transitionProperty: 'width',
        transitionDuration: 220,
      }}
    />
  );
}

Workflow (copy this and tick it off)

Identify the driver: state , layout , gesture , or scroll.
Choose the primitive:
- state → CSS transition / CSS animation
- layout/mount → entering/exiting/layout transitions
- gesture/scroll → shared values + worklets
Keep per-frame work on the UI thread (worklets); avoid React state updates every frame.
If a JS-side effect is required (navigation, analytics, state set), call it via scheduleOnRN.
Verify on-device (Hermes inspector), not “Remote JS Debugging”.

Core patterns

Shared values are the “wire format” between runtimes

Use useSharedValue for numbers/strings/objects that must be read/written from both UI and JS.
Derive styles with useAnimatedStyle.
Prefer withTiming for UI tweens; withSpring for physics.

UI thread vs JS thread: the only rule that matters

Gesture callbacks and animated styles should stay workletized (UI runtime).
Only bridge to JS when you must (via scheduleOnRN).

See: references/worklets-and-threading.md

Gesture Handler: use one API style per subtree

Default to hook API (usePanGesture, useTapGesture, etc.).
Do not nest GestureDetectors that use different API styles (hook vs builder).
Do not reuse the same gesture instance across multiple detectors.

See: references/gestures.md

CSS Transitions (Reanimated 4)

Use when a style value changes due to React state/props and you just want it to animate.

Rules of thumb:

Always set transitionProperty + transitionDuration.
Avoid transitionProperty: 'all' (perf + surprise animations).
Discrete properties (e.g. flexDirection) won’t transition smoothly; use Layout Animations instead.

See: references/css-transitions-and-animations.md

Layout animations

Use when elements enter/exit, or when layout changes due to conditional rendering/reflow.

Prefer presets first (entering/exiting, keyframes, layout transitions). Only reach for fully custom layout animations when presets can’t express the motion.

See: references/layout-animations.md

Scroll-linked animations

Prefer Reanimated scroll handlers/shared values; keep worklet bodies tiny. For full recipes, see:

references/recipes.md

Troubleshooting checklist

“Failed to create a worklet” / worklet not running

Ensure the correct Babel plugin is configured for your environment.
- Expo: handled by babel-preset-expo when installed via expo install.
- Bare RN: Reanimated 4 uses react-native-worklets/plugin.

Gesture callbacks not firing / weird conflicts

Ensure the app root is wrapped with GestureHandlerRootView.
Don’t reuse gestures across detectors; don’t mix hook and builder API in nested detectors.

Needing to call JS from a worklet

Use scheduleOnRN(fn, ...args).
fn must be defined in JS scope (component body or module scope), not created inside a worklet.

Jank / dropped frames

Check for large objects captured into worklets; capture primitives instead.
Avoid transitionProperty: 'all'.
Don’t set React state every frame.

See: references/debugging-and-performance.md

Bundled references (open only when needed)

references/setup-and-compat.md: Expo vs bare setup, New Architecture requirement, common incompatibilities.
references/worklets-and-threading.md: UI runtime, scheduleOnUI/scheduleOnRN, closure capture, migration notes.
references/gestures.md: GestureDetector, hook API patterns, composition, gotchas.
references/css-transitions-and-animations.md: Reanimated 4 CSS transitions/animations quick reference.
references/layout-animations.md: entering/exiting/layout transitions and how to pick.
references/recipes.md: copy-paste components (drag, swipe, pinch, bottom sheet-ish, scroll effects).
references/debugging-and-performance.md: diagnosing worklet issues, profiling, common perf traps.

Quick search

grep -Rni "scheduleOnRN" {baseDir}/references
grep -Rni "transitionProperty" {baseDir}/references
grep -Rni "usePanGesture" {baseDir}/references

Primary docs

Reanimated (v4): https://docs.swmansion.com/react-native-reanimated/
Gesture Handler (latest): https://docs.swmansion.com/react-native-gesture-handler/
Expo Reanimated: https://docs.expo.dev/versions/latest/sdk/reanimated/
Expo Gesture Handler: https://docs.expo.dev/versions/latest/sdk/gesture-handler/

Weekly Installs

Repository

tristanmanchest…t-skills

First Seen

Feb 9, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

gemini-cli91

codex91

opencode91

cursor91

kimi-cli90

amp90

React Native 棕地迁移指南：逐步集成到原生应用（Expo/裸RN）

517 周安装