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

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

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

前言

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

核心组件属性

基础配置属性

source (必需)

• 动画源配置，支持三种形式：
  1. 本地资源路径字符串
  2. 远程资源对象（包含 uri 属性）
  3. 直接传入动画 JSON 对象
• 示例：source={require('./animation.json')}

progress

• 控制动画播放进度，范围 0 到 1
• 更新此属性会使动画跳转到对应进度帧
• 注意：使用命令式 API 时非必需

speed

• 动画播放速度，1 为正常速度
• 负值会使动画反向播放
• 与 duration 属性共存时，duration 优先级更高

duration

• 动画持续时间（毫秒）
• 仅当 source 为 JS 对象时有效
• 示例：设置 2000ms 完成动画 duration={2000}

播放控制属性

loop

• 是否循环播放动画
• 默认值：true

autoPlay

• 组件挂载时是否自动播放
• 仅影响命令式 API
• 默认值：false

样式与渲染

resizeMode

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

style

• 标准 View 样式属性
• 注意：不支持边框样式

webStyle (仅 Web)

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

平台特定属性

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()

• 重置动画到初始状态

pause()

• 暂停当前动画

resume()

• 从暂停处继续播放

资源文件处理指南

资源文件结构

当动画包含外部资源时，JSON 文件中会有如下结构：

"assets": [
  {
    "id": "image_0",
    "w": 737,
    "h": 1215,
    "u": "images/",
    "p": "img_0.png"
  }
]

Android 平台处理

1. 将资源文件放入：android/app/src/main/assets
2. 建议创建 lottie 子目录并按动画分类
3. 在组件中设置路径：imageAssetsFolder={'lottie/animation_1'}

iOS 平台处理

1. 在 Xcode 中右键 Resources 文件夹
2. 选择 "Add file to [Project]"
3. 添加所需图片资源

资源重命名技巧

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

"p": "new_file_name.png"  // 修改此处匹配新文件名

高级功能

颜色滤镜

colorFilters

• 通过 KeyPath 指定图层并应用新颜色
• 格式：[{keypath: "layer", color: "#ff0000"}]

文本替换 (平台特定)

Android:

• textFiltersAndroid: 查找替换文本内容

iOS:

• textFiltersIOS: 通过 KeyPath 指定文本图层并替换

Web 特有功能

hover

• 鼠标悬停时播放动画

direction

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

最佳实践建议

1. 性能优化：

   • 简单动画使用 HARDWARE 渲染模式
   • 复杂动画考虑 SOFTWARE 模式

2. 资源管理：

   • 保持资源文件命名一致
   • 为不同动画创建独立资源目录

3. 错误处理：

   • 实现 onAnimationFailure 回调提供友好错误提示

4. 跨平台兼容：

   • 测试不同平台的动画表现
   • 注意平台特有属性的差异

通过掌握这些 API 和使用技巧，开发者可以在 React Native 应用中创建流畅、吸引人的 Lottie 动画效果。

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