译文地址： https://github.com/bigxixi/lottie-android

Lottie 安卓版, iOS 版, and React Native 版

这是 Lottie 项目说明的中文版，由BigXiXi翻译, 原文地址： https://github.com/airbnb/lottie-android/
Lottie-iOS 版的翻译点这里，由CRAnimation 团队提供。
文中 After Effects 术语参考自官方中文版 AE 。

Lottie 是一个用于 Android 和 iOS 的代码库，可以解析用 Adobe After Effects 制作动画后通过 Bodymovin 插件 导出的 JSON 数据文件并在移动端原生渲染!

前所未有地, 设计师们终于可以创造 并传递 优美的动画给工程师们，再也不用让工程师痛苦地手工还原动画。都说一图胜千言，现在我们有千言万语:

所有这些动画都是在 After Effects 里创作的, 然后用 Bodymovin 插件导出在设备本地直接渲染的，没做任何附加的修改。

Bodymovin 是一款由 Hernan·Torrisi 编写的 After Effects 插件，用于将 After effects 动画导出为 JSON 数据，它包含一个 JavaScript 写的可用于 web 的播放器（译者注：这个播放器直接读取 JSON 数据来播放动画，可以直接用来做网页，这个是 bodymovin 自带的功能）。我们在他的大作的基础上把插件的功能应用于 Android 、 iOS 和 React Native 。

更多细节可以参阅我们的博文。 也可以在推特上和我们互动 @ (gpeal8) 或者给我们写邮件，地址是 [email protected] 。

其他平台

• Web
• Xamarin
• NativeScript
• Appcelerator Titanium

演示 APP

你可以自己编译演示 APP 或者在 Google Play 下载Play Store 地址。这款演示 APP 包含了一些自带的动画例子，当然你也可以从手机本地存储或者网络（通过网盘或 URL ）上加载自己的动画。

下载

Lottie 仅支持用 Gradle 构建配置, 请将依赖项添加到项目 build.gradle 文件中：

dependencies {  
  compile 'com.airbnb.android:lottie:1.5.3'
}

你的项目中使用了 Lottie 吗?

如果你在项目里使用了 Lottie ，可以通过邮件告诉我们（ [email protected] ），我们将很快建立一个页面呈现来自全球的真实用户案例。

如何使用 Lottie

Lottie 支持 ICS (API 14) 及以上版本。 最简单的用法是使用 LottieAnimationView:

<com.airbnb.lottie.LottieAnimationView
        android:id="@+id/animation_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        app:lottie_fileName="hello-world.json"
        app:lottie_loop="true"
        app:lottie_autoPlay="true" />

或者你也可以通过其他程序化的手段来加载。
比如读取在 app/src/main/assets 中的 JSON 文件:

LottieAnimationView animationView = (LottieAnimationView) findViewById(R.id.animation_view);
animationView.setAnimation("hello-world.json");
animationView.loop(true);

这个方法可以在后台异步加载动画文件，并在加载完成后开始渲染动画。

如果你想重用一个动画，例如用在一个列表中的每个条目中或者加载自网络请求的 JSONObject ：

 LottieAnimationView animationView = (LottieAnimationView) findViewById(R.id.animation_view);
 ...
 Cancellable compositionCancellable = LottieComposition.Factory.fromJson(getResources(), jsonObject, (composition) -> {
     animationView.setComposition(composition);
     animationView.playAnimation();
 });

 // 可以用 cancel()方法来停止 composition 的异步加载
 // compositionCancellable.cancel();

然后你可以控制这个动画或者给他加个监听：

animationView.addAnimatorUpdateListener((animation) -> {
    //这里可添加自定义功能
});
animationView.playAnimation();
...
if (animationView.isAnimating()) {
    //这里可添加自定义功能
}
...
animationView.setProgress(0.5f);
...
// 自定义动画速度或时长
ValueAnimator animator = ValueAnimator.ofFloat(0f, 1f)
    .setDuration(500);
animator.addUpdateListener(animation -> {
    animationView.setProgress(animation.getAnimatedValue());
});
animator.start();
...
animationView.cancelAnimation();

本质上说， LottieAnimationView 使用 LottieDrawable 来渲染动画。如有需要，你也可以直接使用 drawable ：

LottieDrawable drawable = new LottieDrawable();
LottieComposition.Factory.fromAssetFileName(getContext(), "hello-world.json", (composition) -> {
    drawable.setComposition(composition);
});

如果你的动画需要频繁重用， LottieAnimationView 自带一个可选的缓存机制 —— LottieAnimationView#setAnimation(String, CacheStrategy)。 CacheStrategy 参数的可选项是 Strong（强）, Weak（弱）, or None（无）， 用以设定 LottieAnimationView 对已加载和解析的动画的引用强弱程度。

图像资源支持

你也可以对图片资源做动画，此时用到的图片需存放在 asset 目录下的一个子目录中。只需调用LottieAnimationView 或 LottieDrawable 中的 setImageAssetsFolder 加载 asset 目录下的相对目录，并保持图片资源的文件名和从 bodymovin 中导出时一致（格式为 img_#.png/jpg ...）。 如果你是直接使用 LottieDrawable ，完成后需用 recycleBitmaps 方法来释放。

如果你需要以网络下载或者其他方式提供图片资源，可以用一个 delegate 来实现：

animationView.setImageAssetDelegate(new ImageAssetDelegate() {
         @Override public Bitmap fetchBitmap(LottieImageAsset asset) {
           getBitmap(asset);
         }
       });

支持的 After Effects 动画类型

译者注： Lottie 目前不支持的 AE 动效类型很多，例如常用的 3D 图层变换、几乎所有效果器[effects]、图层样式[layer styles]、叠加模式[blending mode]、渐变[gradient ramp/gradient fill...]（好像正在加入支持，期待更新）、任意表达式[expressions]、径向擦除[radius wipe]等。。。
在用 AE 制作动画的时候一定要看清楚能否拆解为以下支持的类型。

预合成[Pre-composition]

关键帧插值[Keyframe Interpolation]

• 线性插值[Linear Interpolation]

• 贝塞尔曲线插值[Bezier Interpolation]

• 定格插值[Hold Interpolation]

• 漂浮穿梭时间[Rove Across Time]

• 空间贝塞尔曲线[Spatial Bezier]

固态层[Solids]

• 锚点变换[Transform Anchor Point]

• 位置变换[Transform Position]

• 缩放变换[Transform Scale]

• 旋转变换[Transform Rotation]

• 不透明度变换[Transform Opacity]

蒙版[Masks]

• 蒙版路径[Path]

• 蒙版不透明度[Opacity]

• 多蒙版混合模式（相加、相减、反转）[Multiple Masks (additive, subtractive, inverted)]

轨道遮罩[Track Mattes]

• Alpha 遮罩[Alpha Matte]

父级[Parenting]

• 多个父级[Multiple Parenting]

• 空对象[Nulls]

形状图层[Shape Layers]

• 矩形（所有属性）[Rectangle (All properties)]

• 椭圆（所有属性）[Ellipse (All properties)]

• 多边星形（所有属性）[Polystar (All properties)]

• 多边形（所有属性。点个数必须为整数。）[Polygon (All properties. Integer point values only.)]

• 路径变换（所有属性）[Path (All properties)]

• 锚点变换[Anchor Point]

• 位置变换[Position]

• 缩放变换[Scale]

• 旋转变换[Rotation]

• 不透明度[Opacity]

• 形状组变换（锚点、位置、缩放……）[Group Transforms (Anchor point, position, scale etc)]

• 一个形状组可包含多个形状 [Multiple paths in one group]

形状图层描边 [Stroke (shape layer)]

• 描边颜色[Stroke Color]

• 描边不透明度[Stroke Opacity]

• 描边宽度[Stroke Width]

• 描边端点[Line Cap]

• 虚线[Dashes]

形状图层填充[Fill (shape layer)]

• 填充颜色[Fill Color]

• 填充不透明度[Fill Opacity]

修剪路径[Trim Paths (shape layer)]

• 修剪路径开始[Trim Paths Start]

• 修剪路径结束[Trim Paths End]

• 修剪路径偏移[Trim Paths Offset]

性能和内存占用

1. 如果动画合成中没有遮罩或者蒙版，性能和内存开销会非常棒。此时没有位图生成，大部分操作都是简单的 canvas 画布操作。
2. 如果合成中存在遮罩或者蒙版, 动画将会使用脱屏缓冲区（ offscreen buffer ），性能将会受到影响。
3. 如果你在一个列表中使用动画, 我们建议你配置 LottieAnimationView.setAnimation(String, CacheStrategy) 的第二个参数——缓存策略，这样动画就不必每次都反序列化。

来试试吧

克隆这个库并运行 LottieSample 模块，你将能看到很多示例动画。 动画的 JSON 数据文件存放在 LottieSample/src/main/assets ，原始的 AE 工程文件存放在 /After Effects Samples

示例 APP 同样可以从 url 或本地设备加载并渲染 JSON 文件（比如 downloads 文件夹或者 sdcard ）。

其他方案

1. 手工编写动画代码。 同时为 Android 和 iOS 平台编写动画代码将会耗费巨大的难以预估的设计和开发时间。甚至在花费了如此多时间后仍无法保证可以完美还原动画。
2. Facebook Keyframes. Keyframes 是 Facebook 出品的一个优秀的动画代码库。然而, Keyframes 支持的 AE 动画特性较少，例如 Lottie 所支持的遮罩、蒙版、路径修建、虚线等等它都没有提供支持。
3. Gifs 动画。 Gifs 占用了数倍于 bodymovin 导出的 JSON 文件的大小，而且只能在一个固定的尺寸渲染无法放大适配高分辨率屏幕。（译者注： gif 的问题还有颜色数最高只有 256 色导致的画质不高，画面中的渐变容易出现断层，如果是带透明通道的 gif 几乎都会产出毛边。）
4. Png 图像序列。 Png 图像序列的效果甚至比 gif 还要糟糕，因为它的体积可能达到 json 的几十倍而且同样无法放大。

为什么叫做 Lottie?

Lottie 是以德国剪影动画先驱 Lotte Reiniger （洛特·雷妮格）的名字命名的。 她最出名的作品是《阿基米德王子历险记》 (1926) – 世界上第一部长篇动画电影。 比华尔特·迪士尼的长篇动画电影——《白雪公主与七个小矮人》 (1937) 还要早了 10 年。
洛特·雷妮格的艺术

为 Lottie 做贡献

我们非常欢迎您为 Lottie 贡献力量， 只需提交一个 Pull Request 并附上对你所做改进的描述。
Lottie 使用 Facebook screenshot tests for Android（ Facebook 出品的安卓快照测试工具） 来检测像素级的变动。 请在发起 PR 前运行 ./gradlew --daemon recordMode screenshotTests 来确保没有产生破坏性的改动。请使用模拟器运行搭载 Lollipop 系统的 Nexus 5 来做这个测试。如果快照有变动将会出现在你的 git diff 结果中。

如果你想加入更多的 JSON 文件和快照测试, 可以把测试加入到 LottieTest。

有问题或者功能需求？

任何问题欢迎到 github 的 issues 页面提出。 如果你的 After Effect 文件导出的动画无效, 也请将 AE 工程文件作为附件粘贴到你的 issue 里。没有原始文件的情况下我们也很难诊断问题。