react-native-reanimated 1.x 架构解析:重写 Animated 内核,迈向 100% 声明式手势动画

原创2026-09-15 18:05:521,996 阅读
文章标签:移动开发前端

react-native-reanimated 1.x 架构解析:重写 Animated 内核,迈向 100% 声明式手势动画

react-native-reanimated 是 React Native 官方 Animated 库的重新实现("React Native's Animated library reimplemented"),其核心主张是把动画声明放在 JS 侧、执行放到原生线程,并提供一个更通用的低层节点抽象,从而彻底摆脱 useNativeDriver 标记与"动画对象"这一历史包袱。本文以 v1 版 About 文档 为主线,结合同一版本文档体系中的 declarative.md、clock.md、value.md、nodes/ 系列与 animations/ 系列,深入讲解 v1 的设计动机、"每帧最多求值一次"的求值算法、声明式动画 API 的写法以及它如何实现完全声明式的手势交互。读完本文,你将理解 reanimated v1 的节点图执行模型,并能够用 Clock、set、cond、timing 等节点亲手搭建运行在 UI 线程上的动画。

项目定位:重新实现 Animated 的三大承诺

v1 文档在开篇就给出了项目最凝练的定位:React Native 的 Animated 库重新实现。它围绕这个定位提出三个核心卖点:

  • Native Performance(原生性能):在 JS 中声明动画,但让动画真正运行在原生线程上;
  • Precise Animations(精确动画):API 提供了更高层次的精确性与对动画细节的控制能力;
  • (mostly) Backwards Compatible(基本向后兼容):沿用你已经熟悉的 React Native Animated API,通常不需要改动任何代码即可上手。

在此基础上,reanimated 为 Animated API 提供了一种更全面、更低层的抽象,带来更大的灵活性、控制力与性能。文档特别强调:将其与 react-native-gesture-handler 配合,可以实现高性能的基于手势的交互。这一组合构成了 reanimated 生态中最经典的使用场景。

Motivation:为什么要把 Animated 重新实现一遍

v1 文档用一节专门阐述了项目诞生的动机,这是理解整个架构设计的钥匙。核心问题在于:Animated 库在处理"基于手势的交互"时存在几个难以绕过的局限。

手势拖拽中的"回弹吸附"难题

项目最初是为了解决一个非常具体的交互问题而创建的:一个物体可以被拖拽着在屏幕上移动,松手后它应当"吸附"(snap)到屏幕上的某个位置。当时的做法是使用 Animated.event 把手势状态映射到盒子的位置,并用 useNativeDriver 标记让整个交互跑在 UI 线程上。但即便如此,在手势结束时,仍然必须回调到 JS 线程去启动"吸附"动画。

根因是 Animated.spring({}).start() 无法以"声明式"的方式使用:它一旦执行,就带有一个"副作用"——启动一个会持续更新数值一段时间的过程。而当时 Animated 的执行模型是:每一帧为需要更新的视图遍历并运行其所有依赖节点,如果往这个模型里塞"副作用"节点,很难控制它们不被过度执行——比如导致动画被启动多次。

原生驱动(native driver)的能力缺口

另一个灵感来源是作者 Krzysztof 将 "Animated Tracking"(动画值跟踪)移植到原生驱动(native driver)的工作。尽管 native driver 已经推出很久,但它仍然不支持非原生 Animated 库能做的所有事情。原因很直白:每个功能都要为 JS、Android、iOS 各维护一份实现,修 bug 也要修三份,代价极高。

因此 reanimated 的一个目标就是:提供更通用的 API 构建块,让复杂功能只在 JS 侧实现,把原生代码量压到最小。文档以 diffClamp 节点为例——它在 Animated 核心中被实现于三个不同的地方,尽管这个节点很实用,它其实只有一个典型用例(可折叠 ScrollView 头部)。这种"为单一场景在三处重复实现"的窘境,正是重新设计底层抽象的充分理由。

对社区 PR 的态度

文档还提到了 React Native 的 PR #18029:即使它提供了一个合理的用例,维护者仍对合并持犹豫态度。reanimated 的立场是:Animated API 不应该阻碍用户构建类似的东西,而 react-native-reanimated 的目标正是提供更低层的访问能力,让用户无需改动库核心就能实现这类乃至更多功能。

设计目标:从节点系统到去掉 useNativeDriver

基于上述动机,v1 文档明确列出了项目的目标(goals):

  • 更通用的原始节点类型,促进库内部代码复用,让新增功能和修复 bug 都更容易;
  • 新的一组基础节点足以实现 Animated 兼容 API,包括:
    • 像 diffClamp 这样的复杂节点;
    • 动画值跟踪(animated value tracking)、动画交错(animation staggering)等交互;
  • 条件求值(conditional evaluation)与带副作用的节点(set、startClock、stopClock);
  • 彻底告别 useNativeDriver——所有动画默认跑在 UI 线程上。

这四条目标相互支撑:通用节点是手段,兼容 API 是目的,而条件求值与副作用节点是让"声明式动画"成为可能的关键,最终自然导向"不需要 useNativeDriver"的体验。可以看到,useNativeDriver 在这里不是一个 API 开关,而是整个架构演进后的必然结果。

尚未移植的功能清单(Reanimated overview)

v1 文档坦诚地给出了一个"尚未从原始 Animated 移植"的功能清单,同时强调:这些缺失功能所提供的能力,在 reanimated 中已经可以用不同方法论实现(例如 declarative.md 展示了实现方式可能不同)。清单如下:

  • 使用值偏移(value offsets);
  • 值跟踪(value tracking)——reanimated 不仅支持目标参数,还支持跟踪所有动画参数,可用其他方式实现;
  • 动画交错(animation staggering);
  • 动画延迟(animation delays)。

这份清单是 v1 时代诚实的能力边界声明,也侧面说明了其架构的"少而通用"取向:宁愿提供原子能力,也不在原生侧堆砌特化功能。

核心算法:每帧最多求值一次(At most once evaluation)

v1 与原始 Animated 最大的运行模型差异在于求值次数:原始 Animated 中,同一个节点在一帧内可能被求值多次;而 reanimated 限制每个节点在一帧内最多被求值一次。

这个限制是启用副作用节点的前提——例如 set 或 startClock 这样的节点如果在一帧内被多次执行,会导致动画被反复启动、数值被反复覆盖。当节点被求值(比如求 add 节点的两个输入之和)后,其结果会被缓存;本帧内其他节点若想使用该输出,直接取缓存值而不再重新求值。这一机制同时带来性能收益——可以只求值尽可能少的节点。

v1 文档给出了完整的分帧决策算法,共五步:

  1. 分析事件:每一帧先分析本帧生成的事件(如触摸流),事件可能更新某些动画值;
  2. 更新时钟:更新对应"正在运行"的 clock 节点的值;
  3. 遍历节点树:从本轮被更新的节点出发向下遍历节点树,找出连接到视图的最终节点;
  4. 求值:找到连接到视图属性的节点后对其求值,这会递归触发其输入节点的求值;
  5. 调度下一帧:全部完成后,检查是否存在"运行中"的时钟;若有,则注册回调在下一帧继续执行并回到第 1 步,否则本帧工作结束。

这套算法把"事件 → 时钟 → 节点图 → 视图"串成一条清晰的数据流,是理解 reanimated v1 一切行为的根基:动画不是被"启动"的进程,而是每帧被重新计算的函数式结果。

时钟(Clock):帧时间戳与动画的节拍器

在 Animated 中,"动画对象"是一等公民,功能繁多,需要在 JS 与原生之间维护不少桥接方法。reanimated v1 用**时钟节点(Clock)**取而代之:它是对 Animated.Value 的扩展,每帧被更新为当前帧的时间戳(毫秒)。当 Clock 节点作为输入时,其返回值就是当前帧时间戳。通过专用方法可以停止、启动时钟,也可以查询时钟是否已启动(对应 startClock、stopClock 与 clockRunning 节点)。

因为 Animated.Clock 只是扩展了 Animated.Value,所以凡是能传任意动画节点的地方都能传时钟,这让时钟可以无缝嵌入任意节点运算。关于时钟的具体行为,可参考 clock.md。

声明式动画 API:用节点而非动画对象

v1 声明式 API 的哲学是:不再有"动画对象",而是操作能执行"单步动画"的节点。为了让一个值动起来,需要把这个值赋给一个节点,该节点在若干其他节点的配合下调用"动画步进节点"。可配置的动画步进节点包括 timing、decay 和 spring。

一个完整的 runTiming 示例

declarative.md 给出了声明式动画的标准模板:用一个 Clock 驱动 timing 节点,外部用 cond 判断时钟状态、用 set 重置状态、用 startClock/stopClock 控制时钟启停,最后让 block 返回更新后的 position:

import Animated, { Easing } from 'react-native-reanimated';

const {
  Clock,
  Value,
  set,
  cond,
  startClock,
  clockRunning,
  timing,
  debug,
  stopClock,
  block,
} = Animated;

function runTiming(clock, value, dest) {
  const state = {
    finished: new Value(0),
    position: new Value(0),
    time: new Value(0),
    frameTime: new Value(0),
  };

  const config = {
    duration: 5000,
    toValue: new Value(0),
    easing: Easing.inOut(Easing.ease),
  };

  return block([
    cond(
      clockRunning(clock),
      [
        // 时钟已在运行:仅更新 toValue(例如传入新的目标值)
        set(config.toValue, dest),
      ],
      [
        // 时钟未运行:重置所有动画参数并启动时钟
        set(state.finished, 0),
        set(state.time, 0),
        set(state.position, value),
        set(state.frameTime, 0),
        set(config.toValue, dest),
        startClock(clock),
      ]
    ),
    // 步进节点:更新 position
    timing(clock, state, config),
    // 动画结束则停止时钟
    cond(state.finished, debug('stop clock', stopClock(clock))),
    // block 返回更新后的 position
    state.position,
  ]);
}

export class AnimatedBox extends Component {
  clock = new Clock();
  transX = runTiming(this.clock, -120, 120);

  render() {
    return (
      <View style={styles.container}>
        <Animated.View
          style={[styles.box, { transform: [{ translateX: this.transX }] }]}
        />
      </View>
    );
  }
}

这个示例浓缩了 v1 的全部核心节点:Clock 提供每帧时间戳,block 按顺序求值一组节点并返回最后一个节点的值,cond 依据条件选择分支(详见 cond、block 文档),set 把源节点的值赋给目标值节点(详见 set 文档),startClock/stopClock 控制时钟的启停(分别见 startClock 与 stopClock 文档),clockRunning 则返回时钟是否在运行(1/0,见 clockRunning 文档)。

注意 debug('stop clock', ...) 的用法——debug 节点会在求值时打印日志并透传其值,是 v1 调试节点图的重要工具。

向后兼容 API:timing(value, config).start()

当节点式的写法不便于使用(比如只需要在某个交互里触发一次动画、不想引发视图重渲染)时,v1 还提供了与原始 Animated 相近的调用方式:把 timing 直接作用于一个 Value,然后调用 .start():

class Example extends Component {
  constructor(props) {
    super(props);
    this._transX = new Value(0);
    this._config = {
      duration: 5000,
      toValue: 120,
      easing: Easing.inOut(Easing.ease),
    };
    this._anim = timing(this._transX, this._config);
  }

  render() {
    return (
      <View style={styles.container}>
        <Animated.View
          style={[styles.box, { transform: [{ translateX: this._transX }] }]}
        />
        <Button
          onPress={() => {
            this._anim.start();
          }}
          title="Start"
        />
      </View>
    );
  }
}

这正是"基本向后兼容"承诺的具体体现:同一份 timing 逻辑,既可以在声明式节点图里作为步进节点,也可以像旧 API 一样以"动画对象 + start()"的方式命令式触发。

动画步进节点:timing、spring、decay 的配置细节

三个动画节点在 v1 文档中均有明确的签名与状态约定:

timing

timing(
  clock,
  { finished, position, frameTime, time },
  { toValue, duration, easing }
);

timing 通过基于时间的动画把 position 从当前值运行到 toValue 指定的目标,预期持续 duration 毫秒,并使用 easing(可取 Easing 对象导出的任一缓动节点)。其中:

  • frameTime 会被更新,表示动画已进行的时长(毫秒),即动画进度;
  • time 表示该动画节点最近一次被求值时的时钟时间;
  • finished 在 position 到达最终值,或 frameTime 超过 duration 时被置为 1。

文档特别提醒:frameTime 与 time 在重启动画前必须重置(这正是上面 runTiming 里 set(state.time, 0) 与 set(state.frameTime, 0) 的用意)。完整说明见 animations/timing.md。

spring

spring(
  clock,
  { finished, position, velocity, time },
  {
    damping,
    mass,
    stiffness,
    overshootClamping,
    restSpeedThreshold,
    restDisplacementThreshold,
    toValue,
  }
);

每次求值时,spring 运行单步弹簧动画,更新 position 与 velocity。damping、mass、stiffness、overshootClamping、restSpeedThreshold、restDisplacementThreshold 等参数与原始 Animated API 语义一致(文档建议参阅原始 Animated 文档了解这些参数)。finished 在 position 到达 toValue 目标时置为 1;time 表示节点最近一次求值时的时钟值,重启前同样需要重置。详见 animations/spring.md。

decay

decay(clock, { finished, velocity, position, time }, { deceleration });

decay 每次求值运行单步衰减动画,更新 position 与 velocity;当速度衰减到"无意义"的水平(低于显著性阈值)时,finished 置为 1。time 由节点自动填充为最近一次求值时的时钟时间,重启前需重置。deceleration 控制减速快慢,取值应在 0 到 1 之间,但只有接近 1 的值才会产生有意义的结果——这是 v1 文档给出的明确参数取值范围。详见 animations/decay.md。

Value 与视图连接:把节点映射到 UI 属性

Value 与 useValue

Animated.Value 是存放数值的容器,通过 new Value(0) 构造。为向后兼容,初始化后仍可用 setValue 更新:

const v = new Value(0);
// ...
v.setValue(100);

在函数组件中使用 Animated.Value 时,文档建议用 useRef(...) 或 useMemo(...) 包裹实例化,保证重渲染时复用同一实例,或者直接使用 useValue hook:

const v = useValue(0);
// ...
v.setValue(100);

详见 value.md。

Animated.View 等组件

与原始 Animated 一致,reanimated 要求使用带 Animated. 前缀的组件来接收动画节点作为 props(详见 view.md):

import Animated from 'react-native-reanimated';

// 使用
<Animated.View/>
// 而不是
<View/>

Animated.Code 与 useCode:无视图的节点执行

有时候节点的输出并不直接绑定到视图属性,但仍需要在输入变化时执行。v1 提供 Animated.Code 组件承载这类逻辑:它渲染 null,可以放在 render 中的任意位置,利用 componentDidMount 与 componentWillUnmount 生命周期安装和清理节点。注意其内部代码只会在挂载时执行一次;若想让节点在组件更新时重建,可以修改 Animated.Code 的 key,让 React 卸载旧实例、挂载新实例。它支持 dependencies,行为类似 useCode 的第二个参数。

<Animated.Code>
  {() =>
    block([
      set(this.transX1, add(multiply(-1, this._transX))),
      set(this.transX2, add(multiply(-2, this._transX), 120)),
      set(this.transX3, sub(multiply(2, this._transX), 120)),
      set(this.transX4, add(multiply(1, this._transX))),
    ])
  }
</Animated.Code>

也支持 exec prop 直接传入节点:

<Animated.Code
  exec={block([
    set(this.transX1, add(multiply(-1, this._transX))),
    set(this.transX2, add(multiply(-2, this._transX), 120)),
    set(this.transX3, sub(multiply(2, this._transX), 120)),
    set(this.transX4, add(multiply(1, this._transX))),
  ])}
/>

Animated.useCode(factory, dependencies) 是 Animated.Code 的 hook 版本:第一个参数是返回节点(或节点数组,会被包进 block)的工厂函数,第二个参数是依赖数组;它在组件挂载以及依赖变化时更新节点,在不支持 hooks 的 React Native(< 0.59)上不做任何事。文档建议配合 react-hooks/exhaustive-deps eslint 规则使用。完整说明见 code.md。

100% 声明式手势交互

v1 文档宣称 reanimated "与 Gesture Handler 库配合使用效果最佳",且当时所有示例都基于该库构建,包括终极示例 ImagePreview 应用。

声明式事件处理的关键在于 event 节点的扩展用法:除了提供从事件字段到动画节点的映射,还可以写一个函数,接收 reanimated 值映射作为输入,返回一个 block(或其他 reanimated 函数)。这让事件数据可以在 UI 线程内完成后处理,而不必依赖挂到 Animated.View props 上的节点依赖。详见 event.md:

import { event, set } from 'react-native-reanimated';

this.onGestureEvent = event([
  {
    nativeEvent: {
      translationX: (x) => set(this._x, x),
    },
  },
]);

当需要在 reanimated 代码中使用多个事件属性时,可以把处理函数定义在 nativeEvent 级别。下面的示例同时消费 PanGestureHandler 事件的 translationX、translationY 与 state,并在手势结束时累加偏移量——整个逻辑全部运行在 UI 线程,无 JS 回调:

<PanGestureHandler
  onGestureEvent={event([
    {
      nativeEvent: ({ translationX: x, translationY: y, state }) =>
        block([
          set(this._transX, add(x, offsetX)),
          set(this._transY, add(y, offsetY)),
          cond(eq(state, State.END), [
            set(this.offsetX, add(this.offsetX, x)),
            set(this.offsetY, add(this.offsetY, y)),
          ]),
        ]),
    },
  ])}>
  <Animated.View
    style={{
      transform: [{ translateX: this._transX, translateY: this._transY }],
    }}
  />
</PanGestureHandler>

这正是 Motivation 中那个"拖拽后吸附"难题的声明式解法:因为 set、cond 等副作用/条件节点已经是一等公民,整个手势生命周期(拖拽、结束、偏移累积)都可以在节点图中表达,不再需要"手势结束时回调 JS 再 start 一个动画"。

安装、测试与扩展配置

安装步骤

v1 的安装流程(详见 getting-started.md):

  1. 用 yarn 安装库:
yarn add react-native-reanimated
  1. iOS 平台需在 ios 目录执行 pod install:
cd ios
pod install
  1. 在代码中从 react-native-reanimated 导入,而不是从 react-native 导入:
import Animated from 'react-native-reanimated';

需要 Easing 时同理:

import Animated, { Easing } from 'react-native-reanimated';

v1 文档特别说明:文中提到的带 Animated 前缀的类或方法,除非另行说明,均指从 react-native-reanimated 包导入。

Jest 测试 mock

在 Jest 中使用 reanimated 需要在测试文件顶部加入 mock:

jest.mock('react-native-reanimated', () =>
  require('react-native-reanimated/mock')
);

扩展原生可动画属性

reanimated 导出两个函数,用于控制哪些属性可以在原生侧被动画化(详见 config.md):

  1. addWhitelistedNativeProps():用于会触发布局重算的属性(在 v1 源码 src/ConfigHelper.js 中列出);
  2. addWhitelistedUIProps():用于其他任何属性(src/ConfigHelper.js 中列出当前允许的属性)。

当你想动画化 reanimated 默认不支持的属性时,可以用这两个函数将其加入白名单。

Transitions:实验性的视图层级过渡 API

v1 还附带一个实验性 API——Transitions,用于在两个视图层级状态之间做动画,概念上类似 React Native 的 LayoutAnimation,但提供了更精细的控制(详见 transitions.md)。它由两个核心构件组成:

  • Transitioning.View:普通 View 的扩展,可接受任意 View props,作为所有过渡动画的根节点,通过调用其 animateNextTransition() 触发下一次过渡;
  • 过渡定义:使用 JSX 语法描述过渡动画,所有组件来自 Transition 对象。

分组组件方面,<Transition.Together> 让嵌套的过渡并行执行,<Transition.Sequence> 让过渡按列出顺序依次执行。各过渡组件共享 durationMs(动画时长,毫秒)、delayMs(延迟启动,毫秒)、interpolation(过渡曲线,可选 linear、easeIn、easeOut、easeInOut)与 propagation(按视图位置自动延迟过渡开始,可选 top、bottom、left、right)四个通用属性。具体过渡组件包括:

  • <Transition.In>:定义过渡期间挂载的视图如何动画化,type 可选 fade、scale、slide-top、slide-bottom、slide-left、slide-right;
  • <Transition.Out>:定义过渡期间被移除的视图如何动画化,type 取值同上;
  • <Transition.Change>:定义属性发生变化的组件的过渡动画,目前支持位置、边界与 transform。

由于该 API 是实验性的、随时可能变化,使用前请以示例应用中的实际用法为准。

与现代版本的呼应:从节点图到现代 API

需要说明的是,本仓库当前的主代码(packages/react-native-reanimated/src)已经是多版本迭代后的形态:v1 的 Clock/Value/set/cond 节点体系由当前版本的 useSharedValue、withTiming/withSpring/withDecay 等高层 API 取代,对应的动画模块在 src/animation 目录下仍以 timing.ts、spring/、decay/ 等文件延续着"timing / spring / decay"的三大动画分类。从源码结构可以推断,v1 确立的"动画作为每帧可求值步骤"的思想被保留了下来,只是以新的工作线程模型与 API 形态呈现。v1 文档(version-1.x 全部章节)是理解这一演进的起点:它记录了这个库最初"为什么"与"怎么做"的设计决策。

结语

v1 的 about.md 用很少的篇幅讲清了 reanimated 最重要的三个层面:动机(原生驱动能力不全、副作用节点难以表达、特化节点重复实现)、目标(通用节点、兼容 API、条件求值与副作用节点、去掉 useNativeDriver)与核心算法(每帧最多求值一次 + 五步调度)。配合 declarative.md、clock.md、nodes/ 与 animations/ 系列文档,你可以完整拼出 v1 的运行时图景:Clock 提供帧时间戳,set/cond/block 提供控制流,timing/spring/decay 提供单步物理/时间动画,event 让手势数据在 UI 线程内被消费,最终所有动画默认运行在原生线程——无需 useNativeDriver。这套设计为后续版本奠定了"声明式、UI 线程执行"的基石,也是理解今天 reanimated 系列 API 的最佳入口。

登录后查看全文
react-native-reanimated