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库依赖项。选择适用于您的React Native版本的选项卡。

React Native 0.72
React Native 0.83

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

"dependencies": {
     ...
     "@amazon-devices/lottie-react-native": "~3.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-native API相同的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格式的资产
ColorFilters
测试筛选条件 - Vega上没有与TestFilterIos或TestFilterAndroid对应的筛选条件。

使用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 SDK版本	Vega OS版本	React Native版本
~2.0.x+6.0.0-rc.1	0.23及更早版本	`OS 1.1 (1401010009820)`及更早版本	0.72
~3.0.x+6.0.0-rc.1	0.24	`OS 1.2 (2101020054720)`	0.72、0.83

Vega 库和服务

安装

示例

API

组件API

方法（命令式API）：

Vega上的例外情况

使用ImageAssetsFolder

支持的版本

相关主题

​安装

​示例

​API

​组件API

​方法（命令式API）：

​Vega上的例外情况

​使用ImageAssetsFolder

​支持的版本

​相关主题

安装

示例

API

组件API

方法（命令式API）：

Vega上的例外情况

使用ImageAssetsFolder

支持的版本

相关主题