lottie-react-native
@amazon-devices/lottie-react-native库扩展了Lottie React Native，以在适用于Vega的React Native (RNV) 应用中支持Lottie动画。您在TypeScript和JavaScript RNV项目中都可以使用这个库来运行Lottie动画。
您无需单独安装此库，因为它已预装在RNV应用中。它可作为自动链接库，在运行时连接到您的应用。请记住，只能确保这个库与其对应的RNV版本兼容。
亚马逊建议您在升级RNV版本时也要更新这个库的版本。这种做法有助于保持一致性，并允许您使用最新的功能和改进。
安装
要使用该程序包，请按照以下说明进行操作：
- 在应用的package.json中添加JavaScript库依赖项：
"dependencies": { ... "@amazon-devices/lottie-react-native": "~2.0.0" } - 使用
npm install命令重新安装package-lock.json文件。 - 将您的Lottie动画添加到<应用程序包的根目录>/src/js/resources/。将Lottie动画的图像添加到<应用程序包的根目录>/assets/image/。
在Vega上，您可以将Lottie动画（并非其图像资产）放置在<应用程序包的根目录>/assets/raw/中。
示例
您可以用声明方式使用Lottie，如以下示例所示。
import React from "react";
import LottieView from "@amazon-devices/lottie-react-native";
export default function Animation() {
return (
<LottieView source={require("../path/to/animation.json")} autoPlay loop />
);
}
或者，您可以使用这个命令式API，如以下示例所示。
import React, { useEffect, useRef } from "react";
import LottieView from "@amazon-devices/lottie-react-native";
export default function AnimationWithImperativeApi() {
const animationRef = useRef<LottieView>(null);
useEffect(() => {
animationRef.current?.play();
// 或者通过以下方式设置特定的startFrame和endFrame：
animationRef.current?.play(30, 120);
}, []);
return (
<LottieView
ref={animationRef}
source={require("../path/to/animation.json")}
/>
);
}
API
RNV使用lottie-react-native来增加对Lottie动画的支持，并支持与lottie-react-nativeAPI相同的API。
@amazon-devices/lottie-react-native库不支持iOS、Android和Windows专属属性。
组件API
| 属性 | 描述 | 默认值 |
|---|---|---|
source |
必需 - 动画来源。您既可以用字符串把source作为本地资产引用，也可以用带有uri属性的对象进行远程引用。您还可以使用实际的动画对象，例如require('../path/to/animation.json')。 |
无 |
progress |
介于0和1之间的数字，或介于0和1之间的Animated数字。这个数字表示动画的标准化进度。如果您更新这个属性，动画就会更新到该进度值对应的帧。如果您使用的是通过引用来控制组件的命令式API，则此属性为可选项。 |
0 |
speed |
介于-1和1之间的数字，表示动画的播放速度。发送负值会使动画倒放。 | 1 |
duration |
动画的持续时间，以毫秒为单位在设置时优先于speed。要使用duration，请使用动画的实际JS对象作为source。 |
undefined |
loop |
布尔型标记，表示动画是否应该循环播放。 | true |
autoPlay |
布尔型标记，表示动画是否应在挂载时自动启动。仅在通过引用来控制组件的命令式API中使用autoplay。 |
false |
autoSize |
布尔型标记，表示动画是否应根据动画JSON中的宽度自动调整自身大小。要使用autoSize，请使用动画的实际JS对象作为source。 |
false |
resizeMode |
确定当帧与原始图像尺寸不匹配时如何调整动画视图大小。支持cover、contain和center。 |
contain |
style |
视图的样式属性，符合标准View中的要求。 |
无 |
imageAssetsFolder |
Vega需要该属性以正常使用资产。有些动画依赖于其他图像资产。使用此文件夹路径来存放Lottie动画所需的图像资产。 | 无 |
onAnimationFinish |
回调函数，将在动画完成时调用该函数。使用布尔值isCancelled参数调用，显示动画是完成了还是取消了。仅当您将loop设置为false时才调用。 |
无 |
onAnimationLoad |
回调函数，将在加载动画时调用该函数。仅在动画资产加载时调用一次。 | 无 |
onAnimationJsonLoad |
不再支持。Use onAnimationLoad. |
无 |
onAnimationPlay |
回调函数，将在播放动画时调用该函数。每次调用play() 时都会调用该函数。 |
无 |
onAnimationPause |
回调函数，将在暂停动画时调用该函数。每次调用pause() 时都会调用该函数。 |
无 |
onAnimationResume |
回调函数，将在动画继续播放时调用该函数。每次调用resume() 时都会调用该函数。 |
无 |
方法（命令式API）：
如示例所示，通过使用React.useRef捕获组件，您可以按命令式方式控制Lottie组件。该参考提供了对下面所列方法的访问，您可以使用这些方法对动画的行为进行更精细的控制。
当动画处于与方法相同的状态时，您不能调用这些方法。例如，您不能在动画播放时调用play()。
如果您在动画播放时使用不同的参数调用play()，则该库将使用最近一次调用中传递的参数。
| 方法 | 描述 |
|---|---|
play |
以属性指定的速度播放完动画。当您以play(startFrame, endFrame) 形式调用时，还可以播放动画的一部分。 |
reset |
将动画重置回0进度。 |
pause |
暂停动画。 |
resume |
恢复暂停的动画。 |
Vega上的例外情况
Vega不支持以下操作和API：
- 使用URI将远程资产传递给“source”
.lottie格式的资产ColorFiltersTextFilterVega
使用ImageAssetsFolder
要使用RNV中的imageAssetsFolder属性，请执行以下步骤：
- 将您的图像资产复制到[项目文件夹]/assets/image中。
- 创建lottie子文件夹。如果需要，为每个动画创建子文件夹。
- 在
imageAssetsFolder属性中，使用其相对路径引用该文件夹。例如：imageAssetsFolder={'lottie/animation_1'}。
默认情况下，RNV提供[项目文件夹]/assets/image。对于直接添加到该文件夹的图像，您无需更新imageAssetsFolder。
例如，以下路径不需要更新imageAssetsFolder：[项目文件夹]/assets/image/images/img_0.png。
以下示例显示了JSON结构以供参考。
{
"assets": [
{
"id": "image_0",
"w": 737,
"h": 1215,
"u": "images/",
"p": "img_0.png"
}
]
}
支持的版本
| 程序包名称 | 亚马逊NPM库版本 | Vega OS内部版本号 | Vega SDK版本 | 发布说明 |
|---|---|---|---|---|
@amazon-devices/react-native-gesture-handler |
2.0.0+2.13.0 | OS 1.1 (201010435950) |
0.19 | 作为系统分布式库发布。初始版本不需要进行向后兼容性检查。 |
@amazon-devices/react-native-gesture-handler |
2.0.0+2.13.0 | OS 1.1 (201010438050) |
0.20 |
相关主题
Last updated: 2025年9月30日
