README
- UiLottie 组件使用说明
** 组件用法
*** 动画数据
UiLottie 可以用两种方式传递动画数据，通过 url 或 path 读取动画数据文件，或者直接提供 JSON 格式的数据：
+BEGIN_SRC htmlbars
<UiLottie @path="assets/lottie/example.json" />
{{!-- 或 --}}
<UiLottie @path="https://example.com/lottie/example.json" />
{{!-- 或 --}}
<UiLottie @data={{this.data}} />
+END_SRC
在上面第二个例子里的 this.data 相当于 JSON.parse JSON 文本数据。
*** 渲染方式
UiLottie 支持切换三种渲染方式，分别是 svg canvas 和 html 。
+BEGIN_SRC htmlbars
<UiLottie @path="..." @renderAs="svg" />
<UiLottie @path="..." @renderAs="canvas" />
<UiLottie @path="..." @renderAs="html" />
+END_SRC
svg 是默认渲染方式。三种渲染方式的对比参见：[[https://github.com/airbnb/lottie-web/wiki/Features][渲染方式的特点]]。
*** 自动播放
UiLottie 默认在渲染后自动播放（一次），通过指定 autoplay 参数为 false 可以禁止自动播放。
+BEGIN_SRC htmlbars
<UiLottie @path="..." @autoplay={{false}} />
+END_SRC
*** 循环播放
UiLottie 默认只会播放一次，通过指定 loop 参数为 true 可以开启循环播放模式。
+BEGIN_SRC htmlbars
<UiLottie @path="..." @loop={{true}} />
+END_SRC
*** 指定名称
lottie 可以为每一个 animation 实例指定一个名字，这个名字是每一个 animation 实例的唯一标识符，当同时存在多个 animation 实例的时候可以使用这个名称来指定 API 操作的 animation 实例是哪一个。关于进阶的 API 操作，参加后文的章节。
UiLottie 默认会使用组件的 this.elementId 作为 animation 实例的名字，也可以通过指定 name 参数来设置名字。不过通常是不需要的，因为 UiLottie 总是一个组件渲染一个 lottie animation。
+BEGIN_SRC htmlbars
<UiLottie @path="..." @name="my_animation" />
+END_SRC
*** 是否隐藏
UiLottie 可以通过设定 hidden 参数来切换动画的可见性。
+BEGIN_SRC htmlbars
<UiLottie @path="..." @hidden={{true}} />
+END_SRC
** 事件响应
UiLottie 允许传递多种事件回调函数，在动画播放的不同阶段可以获取相关的信息。
**** onConfigReady 配置参数设定完成后触发，这也是最早响应的事件回调。
**** onDataReady 动画数据接收完毕后触发。远程 url 数据本身有读取时间，所以这个事件可以确定数据加载是否完成了。
**** onDataFailed 如果数据加载或读取失败，则此事件会被触发。
**** onLoadedImages 如果动画数据里包含图片，那么在图片读取完成后此事件会被触发。
**** onDOMLoaded 动画被成功插入 DOM 之后触发，在此事件之后可以安全的操作动画相关的 DOM 元素。
**** onDestroy 当动画被销毁的时候会触发此事件。
**** onEnterFrame 动画由若干帧组成，播放动画就是以一定的速率不断一帧接一帧的渲染，在每一帧开始渲染的时候此事件会被触发。它接收一个参数，具有以下属性：
type事件类型，其值为：enterFramedirection动画方向，1为正向，-1为反向totalTime动画时长，动画的帧数是用时间长度来表示其单位的，单位时长 * 帧数 = 总时长currentTime当前帧时间，其值为数字，但不一定是整数
**** onComplete 当动画播放完毕后会触发此事件，但循环播放的动画并不会触发这个事件。它接收一个参数，具有以下属性：
type事件类型，其值为：completedirection动画方向，1为正向，-1为反向
**** onLoopComplete 对于循环播放的动画，每完成一次循环都会触发这个事件。它接收一个参数，具有以下属性：
type事件类型，其值为：loopCompletedirection动画方向，1为正向，-1为反向currentLoop当前循环次数，其值为正整数
以下用 onComplete 为例演示以下回调函数的定义和使用
+BEGIN_SRC typescript
export default class extends Controller {
onComplete(event) {
console.log(event); // { type: "complete", direction: 1 }
}
}
+END_SRC
+BEGIN_SRC htmlbars
<UiLottie @path="..." @onComplete={{action this.onComplete}} />
+END_SRC
** 进阶控制
*** 获得动画实例
想要更精细的控制动画的行为，首先要做的是在渲染动画的上下文中获取渲染后的动画实例对象，UiLottie 提供了一个 `afterRender` 钩子函数，会在组件创建 lottie 的动画实例对象之后调用并且将这个实例对象传递给外部的上下文。以下是用法示例：
#+BEGIN_SRC typescript
export default class extends Controller {
afterRender(lottie) {
set(this, 'lottie', lottie);
}
}
#+END_SRC
#+BEGIN_SRC htmlbars
<UiLottie @path="..." @afterRender={{action this.afterRender}} />
{{!-- 之后，可以用 {{this.lottie}} 访问这个动画的实例对象了 --}}
#+END_SRC
lottie 动画实例对象拥有很多有用的属性和方法，以下分别举例说明。
*** 显示/隐藏
除了之前说的 ~hidden~ 属性之外，还可以使用 lottie 动画实例对象来操作动画的显示/隐藏状态：
#+BEGIN_SRC typescript
export default class extends Controller {
hideAnimation() {
this.lottie.hide();
}
showAnimation() {
this.lottie.show();
}
}
#+END_SRC
#+BEGIN_SRC htmlbars
<UiLottie @path="..." @afterRender={{action this.afterRender}} />
<button {{action this.hideAnimation}}>隐藏动画</button>
<button {{action this.showAnimation}}>显示动画</button>
#+END_SRC
*** 播放/停止/暂停
这三种操作仅适用于循环播放的动画，单次动画不能播放/停止/暂停：
#+BEGIN_SRC typescript
export default class extends Controller {
playAnimation() {
this.lottie.play(this.lottie.name); // name 是可选的
}
stopAnimation() {
this.lottie.stop(this.lottie.name); // name 是可选的
}
pauseAnimation() {
this.lottie.togglePause(this.lottie.name); // name 是可选的
}
}
#+END_SRC
#+BEGIN_SRC htmlbars
<UiLottie @path="..." @loop={{true}} @afterRender={{action this.afterRender}} />
<button {{action this.playAnimation}}>隐藏动画</button>
<button {{action this.stopAnimation}}>显示动画</button>
<button {{action this.pauseAnimation}}>暂停/恢复动画</button>
#+END_SRC
*** 反向播放/重新播放
这两种操作既可以用于单次动画也可以用于循环动画，对于循环动画，每次切换反向播放之后都会重置 ~currentLoop~ 。
#+BEGIN_SRC typescript
export default class extends Controller {
invertAnimation() {
this.lottie.setDirection(this.lottie.playDirection * -1);
this.lottie.play(this.lottie.name);
}
replayAnimation() {
this.lottie.goToAndPlay(0); // 0 代表动画第一帧，当然也可以从其他帧开始播放
}
}
#+END_SRC
#+BEGIN_SRC htmlbars
<UiLottie @path="..." @loop={{true}} @afterRender={{action this.afterRender}} />
<button {{action this.invertAnimation}}>反向播放</button>
<button {{action this.replayAnimation}}>重新播放</button>
#+END_SRC