Lottie-React-Native 动画在 Android 上不显示的排查与解决

问题现象

在使用 Lottie-React-Native 库时，开发者遇到了一个典型问题：相同的 Lottie JSON 动画文件在 iOS 设备上能够正常显示，但在多款 Android 设备上却完全无法渲染。测试设备包括三星 Galaxy S21 5G、Galaxy A30S 和 小米 Redmi Note 8 Pro 等不同品牌和 Android 版本的设备。

初步排查

开发者首先尝试了以下常见解决方案：

1. 设置 enableMergePathsAndroidForKitKatAndAbove 属性为 true
2. 检查 Android 日志输出
3. 使用 Lottie 官方提供的"Feature Support Checker"验证 JSON 文件兼容性

然而这些常规方法都未能解决问题。值得注意的是，项目中其他 Lottie 动画在 Android 上却能正常显示，这表明问题可能出在这个特定的 JSON 文件上。

深入分析

通过进一步的技术分析，发现问题的根源在于 JSON 文件中的一个特定属性值。在动画文件的根层级中，存在一个高度属性 "h": 102.51802825927734，这个浮点数值导致了 Android 原生 Lottie 库的解析失败。

Android 的 Lottie 原生库在处理这个属性时，期望得到一个整数值，但实际遇到了浮点数，因此抛出了 JsonDataException 异常，错误信息为："Expected an int but was 102.51802825927734 at path $.h"。

解决方案

针对这个问题，最直接的解决方案是将该属性值修改为最接近的整数值：

{
  "v": "5.10.0",
  "fr": 60,
  "ip": 0,
  "op": 60,
  "w": 102,
  "h": 102,  // 修改前是102.51802825927734
  "nm": "ovum",
  "ddd": 0,
  // 其他属性...
}

技术原理

这个问题的本质在于 Lottie 文件格式规范与实现之间的差异。虽然 Lottie 格式规范理论上支持浮点数，但在实际实现中，某些属性（特别是尺寸相关属性）在 Android 平台上被严格要求为整数。这种平台差异导致了 iOS 和 Android 表现不一致的情况。

最佳实践建议

1. 属性值规范化：对于尺寸等属性，建议始终使用整数值
2. 跨平台测试：在 iOS 和 Android 上都要测试动画效果
3. 日志检查：当动画不显示时，仔细检查设备日志输出
4. 工具验证：使用 Lottie 官方提供的验证工具检查文件兼容性
5. 版本控制：确保使用的 Lottie 库版本是最新的稳定版

总结

这个案例展示了跨平台开发中常见的一个问题：相同的代码或资源在不同平台上可能表现出不同的行为。通过深入分析错误日志和理解底层实现原理，开发者能够快速定位并解决这类问题。对于 Lottie 动画开发，特别要注意 JSON 文件中属性值的格式规范，避免使用可能导致平台解析差异的数据类型。