react-native-reanimated

React Native Reanimated库扩展了动画库API，并在使用基于手势的交互时提供了更大的灵活性。

使用Reanimated，您可以轻松创建在用户界面线程上运行的流畅动画和交互。

文档

有关此库及其API的更多信息，请参阅Software Mansion官方文档中的https://docs.swmansion.com/react-native-reanimated/（仅提供英文版）。

安装

选择适用于您的React Native版本的选项卡。请注意，RN 0.83需额外添加@amazon-devices/react-native-worklets依赖项，其提供核心的多线程基础架构，支持worklet——即可以在独立线程（如用户界面线程）上执行的JavaScript函数。Worklet是Reanimated能够流畅运行动画和交互而不阻塞JavaScript线程的基础。

1. 在package.json文件中添加JavaScript库依赖项：

   • React Native 0.72
   • React Native 0.83
   
   

   复制代码 已复制到剪贴板。

   "dependencies": {
         ...
         "@amazon-devices/react-native-reanimated": "~2.0.0",
   }
   

   
   

   复制代码 已复制到剪贴板。

   "dependencies": {
         ...
         "@amazon-devices/react-native-worklets": "~1.0.0",
         "@amazon-devices/react-native-reanimated": "~4.0.0",
   }
   

2. 将Reanimated Babel插件添加到babel.config.js文件中：

   复制代码 已复制到剪贴板。

    module.exports = {
      plugins: [
        ...
        '@amazon-devices/react-native-worklets/plugin',
      ],
    };
   

3. 运行以下命令，清除Metro bundler缓存：

   复制代码 已复制到剪贴板。

   npm start --reset-cache
   

4. 运行npm install命令重新安装package-lock.json文件。

有关其他信息和上下文，请参阅Software Mansion文档中的Installation（仅提供英文版）。

示例

以下示例说明如何使用withTiming方法在无限循环中运行简单动画。

复制代码 复制到剪贴板。

以下示例展示如何使用withSpring函数运行基于弹簧的动画：

复制代码 复制到剪贴板。

API支持

Vega的Reanimated库提供Turbo模块，该模块提供了对下面列出的大多数方法的支持。

Animations

方法	描述
withTiming	根据持续时间和缓动来创建动画。
withSpring	创建基于弹簧的动画。
withDecay	创建模拟摩擦运动物体的动画。动画将以提供的速度开始，并根据给定的减速率逐渐减速，直到停止。
withSequence	一个动画修饰符，可以按顺序运行动画。
withRepeat	一个动画修饰符，可以重复一个动画多次或无限期地运行动画。
withDelay	一个动画修饰符，可以将动画的启动延迟。
withClamp	动画修改器，用于将动画运动范围限定在指定边界内。

核心

方法	描述
useSharedValue	定义组件中的共享值。
useAnimatedStyle	创建样式对象，类似于StyleSheet样式，可以对该样式设置动画。
useAnimatedProps	创建动画属性对象，可以使用共享值对该对象设置动画。
useAnimatedRef	获取视图的引用。与scrollTo和useScrollViewOffset函数一起使用。
useDerivedValue	在现有共享值的基础上创建新的共享值，同时保持共享值的响应性。
createAnimatedComponent	创建React Native组件的动画版本。使用createAnimatedComponent包装组件可让Reanimated对该组件的任何相关属性或样式设置动画。
cancelAnimation	取消与共享值配对的运行动画。

滚动

方法	描述
scrollTo	使用对滚动视图的动画引用，在用户界面线程上提供会达到给定偏移量的同步滚动。执行流畅滚动，无延迟。
useScrollViewOffset	根据ScrollView的偏移量创建动画。hook会自动检测ScrollView是水平还是垂直。
useAnimatedScrollHandler	一个方便的hook，返回一个事件处理程序引用，该引用可以与React Native的可滚动组件一起使用。

设备

方法	描述
useAnimatedSensor	根据来自设备传感器的数据创建动画，这些传感器包括：加速度计、陀螺仪、重力传感器、磁场传感器和旋转传感器。
useReducedMotion	查询减速运动系统设置。

线程

方法	描述
runOnJS	异步运行无法在用户界面线程上运行的非workletized函数。
runOnUI	在用户界面线程上异步运行workletized函数。
createWorkletRuntime	创建一个新的JS运行时，该运行时可用于在可能与JS或用户界面线程不同的线程上运行工作组。

worklet化

worklet化意味着将JavaScript函数转换为可序列化的对象，该对象可以在用户界面线程上复制和运行。函数标有“worklet”。指令由Reanimated Babel插件自动获取并进行worklet化。

实用工具

方法	描述
interpolate	使用线性插值将值从一个范围映射到另一个范围。
clamp	将值限制在指定范围内。
interpolateColor	使用线性插值将输入范围映射到输出颜色。
getRelativeCoords	确定屏幕上相对于给定视图的位置。

高级API

方法	描述
measure	在用户界面线程上同步获取屏幕上视图的尺寸和位置。
useAnimatedReaction	响应共享值的变化。
useFrameCallback	每次帧更新时运行一个函数。
useEvent	一种低级别挂钩，返回一个使用本机事件调用的事件处理程序。用于创建自定义事件处理器挂钩，例如useAnimatedGestureHandler或useAnimatedScrollHandler。
useHandler	一种低级别挂钩，返回上下文对象和值，指示是否应重建worklet。用于创建自定义事件处理器挂钩，例如useAnimatedGestureHandler或useAnimatedScrollHandler。
dispatchCommand	从用户界面线程同步调度原生组件上的命令。
setNativeProps	更新组件属性。
useComposedEventHandler	允许将基于useEvent的事件处理程序（例如useAnimatedScrollHandler或自定义处理程序）合并为单个组合事件处理器。
makeMutable	在useSharedValue挂钩内部用于创建共享值。

例外情况

Vega上的Reanimated库在API支持方面有一些例外。

Vega不支持以下挂钩和方法：

• useAnimatedSensor
• useAnimatedKeyboard
• useReducedMotion
• 结构上的Layout Animations
• CSS转换
• CSS Animations
• SET（共享元素转换）

Vega已知问题

• 使用快速刷新后，使用withRepeat的动画停止重复。
• 使用快速刷新后，动画上的样式不会更新。

支持的版本

NPM程序包版本	Vega SDK版本	Vega OS版本	React Native版本
~2.0.x+3.5.4	0.23及更早版本	操作系统1.1 (1401010009820)及更早版本	0.72
~4.0.x+4.1.3	0.24	操作系统1.2 (2101020054720)	0.72、0.83

其他资源

有关其他库的信息，请参阅支持的第三方库和服务。

Credits

该项目的构建和维护工作得到了Shopify、Expo.io和Software Mansion的支持。

---

Last updated: 2026年7月10日