从 1.x 迁移到 2.x：react-native-reanimated 渐进式迁移指南（interpolateNode 与 EasingNode）

从 1.x 迁移到 2.x：react-native-reanimated 渐进式迁移指南（interpolateNode 与 EasingNode）

【免费下载链接】react-native-reanimatedReact Native's Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated

本文基于react-native-reanimated官方 v3.x 文档中的 migration-from-1.x.md 撰写，系统梳理从 Reanimated 1.x 迁移到 2.x 时的设计思路、命名冲突处理策略与两个必须关注的重命名方法，并辅以仓库内 v1.x 历史文档与当前源码进行佐证。读完本文，你将掌握新旧 API 共存的渐进式迁移方法，能够在自己的动画代码中准确区分并替换interpolate/Easing的旧版用法，并为后续平滑升级到 3.x 做好准备。

迁移背景：为什么 1.x 可以渐进式迁移

Reanimated 1 与 Reanimated 2 在底层执行模型上差异巨大：1.x 基于在 JS 线程上运行的动画节点图（node graph），而 2.x 将 worklet 直接调度到 UI 线程执行。理论上这属于破坏性重构，但官方在迁移策略上做了一个关键决策：

安装 Reanimated 2 之后，旧 API 与新 API 可以同时使用。

也就是说，升级依赖后不需要一次性重写全部动画代码，可以逐文件、逐动画地迁移。同一个包内保留了最新稳定版 Reanimated 1 的 API，开发者可以在新代码里使用 2.x 的新写法，同时让旧代码暂时继续运行，实现平滑过渡。

这一策略的直接后果是引入了"命名冲突"问题——新旧两套 API 存在于同一个命名空间中，必然会出现同名函数。官方解决冲突的原则是：

只要与 Reanimated 1 发生命名冲突，就重命名 Reanimated 1 版本的方法，以保持 Reanimated 2 的命名更干净。

换句话说，新 API 的名称是"一等公民"，被保留下来；旧 API 被迫改名，以Node后缀等标识符区分。这样做的代价是引入了一小部分破坏性变更，但受益于"被重命名的方法数量相对较少，而且这些方法的使用频率本身也不高"，迁移成本被控制在可接受范围内。

从仓库中的 v3.x 迁移文档 migration-from-2.x.md 可以看到这一策略的最终走向：Reanimated 3.x 已经完全移除Reanimated 1.x API，任何 2.x 代码无需修改即可运行在 3.x 上。因此，"尽快完成 1.x → 2.x 的迁移"成为能否顺利升级到 3.x 的前提条件。

重命名方法总览

官方明确列出了两个需要开发者手工处理的重命名方法，这是 1.x → 2.x 迁移中仅有的两处 API 破坏性变更：

1.x 旧名称	2.x 新名称	迁移动作
interpolate（作为模块函数导入）	interpolateNode	修改 import 与调用处
Easing（作为模块对象导入）	EasingNode	修改 import 与调用处

需要注意的是，重命名仅针对从react-native-reanimated包直接导入的函数/对象。如果你使用的是AnimatedValue实例上的类成员方法（详见下文），则无需任何改动。

重命名 1：interpolate→interpolateNode

旧版用法（1.x）

在 Reanimated 1.x 中，interpolate是动画节点系统的一部分，需要传入一个节点作为第一个参数，并提供一个配置对象。仓库中的 v1.x 历史文档 nodes/interpolate.md 完整记录了其签名：

interpolate(node, { // Input range for the interpolation. Should be monotonically increasing. inputRange: [nodeOrValue...], // Output range for the interpolation, should be the same length as the input range. outputRange: [nodeOrValue...], // Sets the left and right extrapolate modes. extrapolate?: Extrapolate.EXTEND | Extrapolate.CLAMP | Extrapolate.IDENTITY, // Set the left extrapolate mode, the behavior if the input is less than the first value in inputRange. extrapolateLeft?: Extrapolate.EXTEND | Extrapolate.CLAMP | Extrapolate.IDENTITY, // Set the right extrapolate mode, the behavior if the input is greater than the last value in inputRange. extrapolateRight?: Extrapolate.EXTEND | Extrapolate.CLAMP | Extrapolate.IDENTITY, })

其中三种外推（extrapolate）模式的含义为：

• Extrapolate.EXTEND：超出范围时按当前斜率线性延伸；
• Extrapolate.CLAMP：超出范围时钳制在边界值；
• Extrapolate.IDENTITY：超出范围时直接返回输入值本身。

典型用法是结合concat生成带单位的字符串，例如 1.x 中把 0～360 的节点值映射为旋转角度：

concat( interpolate(node, { inputRange: [0, 360], outputRange: [0, 360] }), 'deg' );

此外，v1.x 文档特别提示：颜色插值不要用interpolate，应使用interpolateColors（见 nodes/interpolateColors.md），因为旧版interpolate对字符串类型（如颜色）的输出支持有限。

迁移后的写法（2.x）

在 2.x 中，如果代码里是"从react-native-reanimated直接 import 的interpolate"这种 1.x 用法，应改为interpolateNode：

import { interpolateNode } from 'react-native-reanimated';

而新 API 的同名函数interpolate则属于 2.x 的 worklet 体系，其函数签名完全不同——不再接收节点和配置对象，而是接收三个位置参数。当前仓库源码 interpolation.ts 中定义了该函数：

export function interpolate( value: number, inputRange: readonly number[], outputRange: readonly number[], type?: ExtrapolationType ): number

从源码可以看出，新版interpolate是一个标注了'worklet'的函数，在 UI 线程上直接对数值进行线性映射：inputRange与outputRange必须至少包含两个值，否则会抛出[Reanimated] Interpolation input and output ranges should contain at least two values.的运行时错误；插值区间内部通过二分查找定位value所处的分段，再调用内部插值逻辑，外推行为由第四参数type控制（默认两侧均为Extrapolation.EXTEND）。

新旧两个同名函数并存，正是命名冲突的直接体现——因此迁移时务必确认：凡是旧式节点风格的interpolate(node, { ... })调用，一律改名interpolateNode；凡是新式interpolate(value, inputRange, outputRange)调用，保持interpolate不变。

重命名 2：Easing→EasingNode

第二个重命名针对缓动函数模块。1.x 中从react-native-reanimated导入的Easing，在 2.x 中应改为EasingNode：

// 1.x import { Easing } from 'react-native-reanimated'; // 2.x（沿用 1.x 节点风格时） import { EasingNode } from 'react-native-reanimated';

Easing模块本身承载了一整套缓动曲线函数。当前仓库源码 Easing.ts 对模块能力有系统说明，可帮助理解旧版EasingNode背后的函数集合：

• 预定义动画：back（先回退再前进）、bounce（弹跳）、ease（惯性缓动）、elastic（弹性交互）；
• 标准函数：linear、quad、cubic，以及可用poly实现的 quartic、quintic 等高次幂函数；
• 附加数学函数：bezier（三次贝塞尔曲线）、circle（圆形缓动）、sin（正弦缓动）、exp（指数缓动）；
• 修饰辅助函数：in（正向运行）、out（反向运行）、inOut（对称化）。

从源码看，这些缓动函数全部以'worklet'标注，例如linear实现为f(t) = t，ease内部通过Bezier(0.42, 0, 1, 1)(t)实现标准惯性曲线（Easing.ts）。

因此，如果代码中仍在使用 1.x 的节点风格动画（如Animated.timing配合Easing节点），迁移时只需把导入名称改为EasingNode；如果已经切换到 2.x 的withTiming等新 API，则继续使用Easing即可（新版Easing在 index.ts 中被正式导出）。

无需改动的场景：AnimatedValue.interpolate

并非所有interpolate都需要改名。官方明确指出：

如果使用的是类成员方法AnimatedValue.interpolate，则无需任何改动。

也就是说，如果你在 1.x 中是通过Animated.Value实例调用插值，例如：

const value = new Animated.Value(0); value.interpolate({ inputRange: [0, 100], outputRange: [0, 1] });

这种实例方法调用不构成命名冲突，AnimatedValue.interpolate在 2.x 中继续保留原名，直接沿用即可。

迁移路线图与后续升级

综合本指南与 v3.x 的 migration-from-2.x.md 文档，推荐的迁移路线为：

1. 升级到 2.x：安装 Reanimated 2.x 后，新旧 API 同时可用，业务代码不阻塞。
2. 逐处替换旧 API：
   • 将模块级导入的interpolate改为interpolateNode；
   • 将模块级导入的Easing改为EasingNode；
   • AnimatedValue.interpolate实例方法保持原样；
   • 新写的动画代码优先使用 2.x 的useSharedValue、useAnimatedStyle、withTiming、withSpring以及新签名interpolate(value, inputRange, outputRange)。
3. 验证功能等价性：替换后核对插值范围与外推模式（EXTEND/CLAMP/IDENTITY）是否保持原有行为，颜色插值确认已改用interpolateColors。
4. 升级到 3.x：2.x → 3.x 在 API 层面不引入任何破坏性变更，且 3.x 已彻底移除 1.x API——完成前两步后即可无障碍升级。

小结

Reanimated 1.x → 2.x 的迁移被刻意设计为渐进式：新旧 API 在同一包内共存，官方通过"重命名旧 API"而非"破坏新 API"的方式解决命名冲突。开发者实际需要处理的只有两处——interpolate→interpolateNode、Easing→EasingNode，而AnimatedValue.interpolate类成员方法无需改动。尽早完成这两处替换，即可为后续平滑升级到完全移除 1.x API 的 3.x 版本铺平道路。

进一步参考：

• v1.x 插值节点文档 与 v1.x 颜色插值文档：了解旧 API 的完整签名与边界行为；
• v3.x 从 2.x 迁移文档：确认 2.x → 3.x 无破坏性变更；
• 新版 interpolate 源码 与 Easing 模块源码：理解新 API 的工作机制与可用缓动函数全集。

【免费下载链接】react-native-reanimatedReact Native's Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated