react-native-reanimated

React Native Reanimated提供了更全面的低级别抽象，以便在此基础上构建动画库API，因此具有更大的灵活性，尤其是在基于手势的交互方面。

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

文档

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

安装

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

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

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

2. 将@amazon-devices/react-native-reanimated插件添加到您的babel.config.js:

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

    module.exports = {
      plugins: [
        ...
        '@amazon-devices/react-native-reanimated/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	withTiming让您可以根据持续时间和缓动来创建动画。
withSpring	withSpring让您可以创建基于弹簧的动画。
withDecay	withDecay让您可以创建模拟摩擦运动物体的动画。动画将以提供的速度开始，并根据给定的减速率逐渐减速，直到停止。
withSequence	withSequence是一个动画修饰符，让您可以按顺序运行动画。
withRepeat	withRepeat 是一个动画修饰符，让您可以重复一个动画给定次数或无限期地运行动画。
withDelay	withDelay是一个动画修饰符，让您可以将动画的启动延迟。

核心

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

滚动

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

设备

方法	描述
useAnimatedKeyboard	useAnimatedKeyboard让您可以根据当前键盘位置创建动画。
useAnimatedSensor	useAnimatedSensor让您可以根据来自设备传感器的数据创建动画，这些传感器包括：加速度计、陀螺仪、重力传感器、磁场传感器和旋转传感器。
useReducedMotion	useReducedMotion让您可以查询减弱动态效果系统设置。

线程

方法	描述
runOnJS	runOnJS让您可以异步运行非worklet化*函数，这些函数原本无法在用户界面线程上运行。
runOnUI	runOnUI让您可以在用户界面线程上异步运行worklet化函数。
createWorkletRuntime	createWorkletRuntime让您可以创建一个新的JS运行时，该运行时可用于在和JS或用户界面线程不同的线程上运行worklet。

worklet化

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

实用工具

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

高级API

方法	描述
measure	measure让您可以同步获取屏幕上视图的尺寸和位置，全部都在用户界面线程上进行。
useAnimatedReaction	useAnimatedReaction让您可以响应共享值的变化。
useFrameCallback	useFrameCallback让您可以在每次帧更新时运行一个函数。
useEvent	useEvent是低级别hook返回事件处理程序，将与原生事件一起引用，应使用它来创建自定义事件处理程序hook，例如useAnimatedGestureHandler或useAnimatedScrollHandler。
useHandler	useHandler是一个低级别hook，返回上下文对象和值，该值指示是否应重建worklet。应使用它来创建自定义事件处理程序hook，如useAnimatedGestureHandler或useAnimatedScrollHandler。
dispatchCommand	dispatchCommand让您可以从用户界面线程同步调度原生组件上的命令。
setNativeProps	setNativeProps让您可以强制更新组件属性。

Vega上的Reanimated库在API支持方面有一些例外。本部分会解释这些例外情况。

1. Vega平台不支持useAnimatedSensor。在FireTV上，目前为止尚不支持传感器。
2. Vega平台不支持useReducedMotion。对于Vega，目前还没有启用/禁用减弱动态效果的设置。
3. Layout Animations尚未在Fabric上实现，因此Vega平台不支持它们。
4. SET（共享元素转换）让您可以平滑地将一个屏幕上的组件转换为另一个屏幕上的组件。这是一项实验性功能，在Vega上尚不支持。

Vega已知问题

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

支持的版本

程序包名称	亚马逊NPM库版本	OSS NPM库版本	Vega OS内部版本号	Vega SDK版本	发行说明
@amazon-devices/react-native-reanimated	2.0.0+3.5.4	3.5.4	OS 1.1 (201010435950)	0.19	作为系统分布式库发布。初始版本不需要进行向后兼容性检查。

其他资源

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

Credits

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

---

Last updated: 2025年10月13日