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

姬珊慧Beneficient

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

阅读量256

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01031/article/details/148375498

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

lottie-react-native 项目地址: https://gitcode.com/gh_mirrors/lot/lottie-react-native

前言

Lottie-React-Native 是一个强大的 React Native 动画库，它允许开发者在移动应用中轻松使用 Adobe After Effects 动画。本文将全面解析该库的组件 API 和使用方法，帮助开发者更好地掌握这一工具。

核心组件属性解析

基础配置属性

source (必需)

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

progress

范围 0 到 1 的数值，表示动画的进度
更新此属性会使动画跳转到对应进度帧
注意：使用命令式 API 时非必需

speed

动画播放速度
正数表示正向播放，负数表示反向播放
默认值为 1（正常速度）

duration

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

播放控制属性

loop

布尔值，控制是否循环播放
默认 true（循环播放）

autoPlay

布尔值，控制组件挂载时是否自动播放
仅影响命令式 API
默认 false（不自动播放）

样式与布局

resizeMode

动画视图的缩放模式
可选值：cover（覆盖）、contain（包含）、center（居中）
默认 contain

style

标准 View 组件的样式属性
支持除边框样式外的所有布局属性

webStyle (仅 Web)

Web 平台专用样式
使用 CSSProperties 类型

平台特定属性

imageAssetsFolder (仅 Android)

指定 Android 平台资源文件夹路径
iOS 会忽略此属性

useNativeLooping (仅 Windows)

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

renderMode (iOS/Android)

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

回调函数

onAnimationLoaded

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

onAnimationFailure

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

onAnimationFinish

动画播放完成时触发
参数：isCancelled（布尔值，表示是否被取消）
注意：仅在 loop=false 时触发

onAnimationLoop (Windows/Web)

动画每次循环时触发

命令式 API 方法

Lottie-React-Native 提供了强大的命令式控制方法：

play([startFrame, endFrame])
- 播放动画
- 可指定起始帧和结束帧（Web 平台不支持）
reset()
- 重置动画到初始状态（进度 0）
pause()
- 暂停当前动画
resume()
- 从暂停处恢复播放

资源文件处理指南

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

Android 平台处理

将资源图片复制到 android/app/src/main/assets 目录
建议创建子目录组织资源，如 lottie/animation_1
在组件中设置 imageAssetsFolder 属性指向该目录

iOS 平台处理

在 Xcode 中打开项目
右键点击 Resources 文件夹
选择 "Add file to [Project]"
选择需要添加的资源图片

资源重命名技巧

如需重命名资源文件，必须同时修改 JSON 文件中的对应引用：

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

高级功能

颜色过滤

通过 colorFilters 属性可以动态修改动画颜色：

接收一个对象数组
每个对象指定 KeyPath 和新的颜色值（十六进制字符串）

文本替换

Android (textFiltersAndroid)

查找并替换文本内容

iOS (textFiltersIOS)

通过 KeyPath 定位文本层并替换内容

Web 平台特有功能

hover

鼠标悬停时播放动画

direction

播放方向：1（正向）或 -1（反向）

最佳实践建议

对于复杂动画，建议使用硬件加速（HARDWARE）渲染模式
在 Android 平台启用缓存（cacheComposition=true）可提升性能
修改资源文件后必须完全重新构建应用
使用命令式 API 时，合理管理播放状态以避免冲突
对于循环动画，考虑使用平台级循环（仅 Windows）以获得更流畅的效果

通过掌握这些 API 和技巧，开发者可以充分发挥 Lottie-React-Native 的潜力，为应用创建丰富、流畅的动画体验。

lottie-react-native 项目地址: https://gitcode.com/gh_mirrors/lot/lottie-react-native

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考