Lottie-React-Native 组件 API 详解与使用指南

邵冠敬Robin

于 2025-06-02 09:04:19 发布

阅读量300

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00471/article/details/148375502

Lottie-React-Native 组件 API 详解与使用指南

lottie-react-native Lottie wrapper for React Native. 项目地址: https://gitcode.com/gh_mirrors/lo/lottie-react-native

概述

Lottie-React-Native 是一个强大的动画库，它允许开发者在 React Native 应用中轻松使用 Adobe After Effects 动画（通过 Bodymovin 插件导出为 JSON 格式）。本文将全面解析该库的核心 API 和使用技巧，帮助开发者高效地集成和控制动画效果。

核心属性解析

基础配置属性

source (必需)

动画数据源，支持三种形式：
1. 本地资源路径字符串
2. 远程资源对象（包含 uri 属性）
3. 直接传入动画 JS 对象（如通过 require 导入的 JSON 文件）

progress

动画进度控制（0 到 1 之间的数值）
更新此属性会使动画跳转到对应进度帧
注意：使用命令式 API 时非必需

speed

动画播放速度（1 为正常速度）
负值会使动画反向播放

duration

动画持续时间（毫秒）
优先级高于 speed 属性
仅当 source 为 JS 对象时有效

播放控制属性

loop

是否循环播放（默认为 true）

autoPlay

是否在组件挂载时自动播放（默认为 false）
仅影响命令式 API

resizeMode

动画视图的缩放模式：
- cover：填充整个容器，可能裁剪
- contain：保持宽高比完整显示
- center：居中显示，不缩放

平台特定属性

imageAssetsFolder (Android 专用)

指定包含动画资源的文件夹路径
iOS 会忽略此属性

useNativeLooping (Windows 专用)

使用平台级循环提升流畅度
副作用：onAnimationLoop 不会触发，修改 loop 属性会重置播放

renderMode (iOS/Android)

渲染加速模式：
- HARDWARE：硬件加速
- SOFTWARE：软件渲染
- AUTOMATIC：自动选择（默认）

回调函数

onAnimationLoaded

动画加载完成时触发（无参数）

onAnimationFailure

动画处理过程中出错时触发
参数：包含错误信息的字符串

onAnimationFinish

动画播放完成时触发
参数：isCancelled（是否被中途取消）
注意：仅在 loop=false 时触发

onAnimationLoop (Windows/Web)

动画每次循环时触发

命令式 API 方法

play([startFrame, endFrame])

从头播放动画（可指定起始和结束帧）
Web 平台不支持帧区间播放

reset()

重置动画到初始状态（进度为 0）

pause()

暂停当前动画

resume()

从暂停处继续播放

资源文件处理指南

当动画包含外部资源（如图片）时，需要特别注意平台差异：

Android 平台配置

将资源图片放入项目目录：android/app/src/main/assets/
建议创建子目录结构（如 lottie/animation_1/）
在组件中设置对应路径：imageAssetsFolder={'lottie/animation_1'}

iOS 平台配置

在 Xcode 中右键点击 Resources 文件夹
选择 "Add file to [Project]"
导入所需图片资源

资源重命名技巧

如需修改资源文件名，必须同步更新 JSON 文件中的引用：

{
  "assets": [
    {
      "id": "image_0",
      "p": "new_file_name.png"  // 修改此处匹配新文件名
    }
  ]
}

最佳实践建议

性能优化：
- 对复杂动画优先使用 HARDWARE 渲染模式
- Android 平台合理使用 cacheComposition
- Windows 平台考虑 useNativeLooping
错误处理：
- 始终实现 onAnimationFailure 回调
- 在 onAnimationLoaded 中处理加载完成状态
跨平台兼容：
- 注意标记为平台专用的属性
- 为 Web 平台单独配置 webStyle
资源管理：
- 保持资源文件组织结构清晰
- 修改资源后务必重新构建应用