Lottie4J 1.2.0 发布：新增 dotLottie 支持、标记回放与性能大幅提升

Lottie4J 1.2.0 版本现已发布，这又是一个重磅更新！本次更新的重头戏是支持 .lottie 容器格式，但这仅仅是个开始。该版本还带来了基于标记的播放、裁剪功能、自适应渲染、显著的性能提升，以及针对更复杂真实动画测试所驱动的大量核心模型修复。

dotLottie 文件支持

在此之前，Lottie4J 仅支持纯 JSON 格式 (.json)。这是原始的 Lottie 格式，但 LottieFiles 随后引入了一种更新的容器格式：.lottie。它本质上是一个 ZIP 压缩包，可以包含一个或多个动画、嵌入的图像、声音以及描述内容清单的清单文件 (manifest)。

.lottie 格式是一项实用的改进：它使 Lottie 文件更小且自成一体，将图像和其他资源与动画数据捆绑在一起，而无需依赖外部引用。现在，Lottie4J 可以通过核心的 FileLoader 直接加载 .lottie 文件。目前提供两种加载模式：

$ java

// 从 .lottie 文件加载第一个动画（最简单的方式）
LottieAnimation animation = FileLoader.load(path);

// 加载完整的 .lottie 容器以访问清单和所有动画
DotLottie lottie = FileLoader.loadDotLottie(path);

Lottie 对象允许您访问清单（作者、版本元数据）以及动画的完整列表。目前，我发现的大多数实际使用的 .lottie 文件仅捆绑了一个动画，但该 API 已经为未来出现的多动画文件做好了准备。

新播放器功能

标记间播放

Lottie 动画可以嵌入命名标记。这些是动画 JSON 内部的时间戳标签，用于指示兴趣点或循环区域。这是 Lottie4J 之前已解析但未在播放器中公开的功能，现在已完全支持。

新的 play(startMarker, endMarker) 方法可以让播放器从第 1 帧开始，并在时间轴上的两个指定位置之间进行循环播放。

裁剪支持

LottiePlayer 现在支持通过 crop(top, right, bottom, left) 进行裁剪。这允许您将渲染输出剪切为动画画布的子区域，当您只想将动画的一部分嵌入布局而不修改原始文件时，这非常方便。

可调整大小的播放器

LottiePlayer 现在可以正常调整大小并据此调整渲染效果。调整大小还有一个次要影响：较小的尺寸会降低渲染负载，因此在需要时，您可以通过牺牲尺寸来换取性能。

性能优化

此版本的渲染速度有了显著提高。主要的性能增益来自减少了每帧的渲染通道数，并为图层和预合成渲染元数据增加了缓存层，从而避免了在复杂动画上进行重复计算。

差异是显而易见的：一个以前以 20-30 FPS 播放的测试动画现在可以达到约 50 FPS。一个之前在 11 FPS 时运行困难的较重动画，现在在全尺寸下可达到约 31 FPS，并且随着播放器尺寸的缩小，性能还会进一步提升。

自适应渲染模式

新增的自适应渲染开关 setAdaptiveOffscreenScalingEnabled(enabled) 可用于在渲染清晰度和速度之间进行权衡。在自适应模式下，JavaFX 使用更快的渲染路径，这可能会在某些元素上产生轻微的模糊（特别是在某些尺寸下的清晰文本或精细细节）。在非自适应模式下，渲染是像素级的，但速度较慢。

哪种模式效果更好取决于动画：简单的动画通常在自适应模式下看起来不错且能受益于速度提升，而文本密集型或细节丰富的动画则最好保留在默认模式下。该开关在 LottiePlayer 和文件查看器中均有提供，以便您可以测试特定的动画效果。

核心模型改进

本版本对核心库进行了大量改进，这些改进主要源于对更复杂的真实世界 Lottie 文件的测试：

合并和修饰符形状支持：一种在复杂动画中使用的形状图层功能。
混合模式支持：图层现在可以携带影响合成的混合模式指令。
空间贝塞尔插值：位置动画现在能够正确使用贝塞尔曲线而非线性路径进行插值，从而产生使 Lottie 动画更具质感的平滑运动效果。
缺失的模型字段：修复了掩码（mask）、图层（layer）和动画对象中导致特定文件渲染错误的缺失项。
改进的 JSON 输出：当从模型重新创建 Lottie JSON（写入路径）时，值的顺序现在更加一致，重构后的文件与原始文件更加接近。

Jackson 3 升级

核心库已升级至 Jackson 3。这是一个重大的版本迭代：组 ID 从 com.fasterxml.jackson 变更为 tools.jackson。因此，如果您直接依赖核心库并且也自行引入了 Jackson，则需要将其统一为版本 3。此次升级还包括与 CVE 相关的依赖项更新以及迁移过程中产生的后续兼容性修复。

请注意，jackson-annotations 尚未迁移到 tools.jackson 组 ID，目前仍保持在之前的坐标。

调试工具更新

LottieFileDebugViewer 经过重构，将重复的 WebView JavaScript 桥接代码提取到了可重用的组件中。FX 和 JS 的并排视图得到了改进，比较测试也具备了更好的帧同步功能。新增的验证模式会在调整后的尺寸下测试播放器，以验证渲染效果在缩放时是否依然稳定。

自动化的 CompareFxViewWithWebViewTest（它逐帧渲染 JavaFX 和 JavaScript 播放器并检查视觉相似性）现在也支持使用 .lottie 文件了。

尝试使用

更新您的 Maven 依赖：

$ xml

<!-- 仅核心模型，不含播放器 -->
<dependency>
    <groupId>com.lottie4j</groupId>
    <artifactId>core</artifactId>
    <version>1.2.0</version>
</dependency>

<!-- JavaFX 播放器 -->
<dependency>
    <groupId>com.lottie4j</groupId>
    <artifactId>fxplayer</artifactId>
    <version>1.2.0</version>
</dependency>

完整的更改列表可在 GitHub 上查看。

后续计划

自动比较测试目前仍无法在 GitHub Actions 上运行，因为它需要显示环境。本周随 Java 26 一起发布的 JavaFX 26 包含了无头（headless）渲染支持，这或许使得在 GitHub Actions 上运行视觉回归测试成为可能。这是接下来的研究方向。

一如既往：如果您遇到无法正确渲染的 Lottie 文件，请提交 Issue 并附上截图。测试的真实文件越多，库的性能就越完善。

分类导航