1# Lottie 2 3提供Lottie动画。 4 5> **说明：** 6> 7> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10 11## 导入模块 12 13``` 14import lottie from '@ohos/lottieETS' 15``` 16 17> **说明：** 18> 19> 在第一次使用Lottie之前，需要在Terminal窗口运行 `ohpm install @ohos/lottieETS` 命令下载Lottie。 20> 21 22 23## lottie.loadAnimation 24 25loadAnimation( 26 27path: string, container: object, render: string, loop: boolean, autoplay: boolean, name: string ): AnimationItem 28 29加载动画，须提前声明Animator('__lottie_ets')对象，并在Canvas完成布局后调用。可配合Canvas组件生命周期接口onReady()使用。 30 31**参数：** 32 33| 参数 | 类型 | 必填 | 描述 | 34| -------------- | --------------------------- | ---- | ---------------------------------------- | 35| path | string | 是 | hap包内动画资源文件路径，仅支持json格式。示例：path: "common/lottie/data.json" | 36| container | object | 是 | canvas绘图上下文，声明范式需提前声明CanvasRenderingContext2D。 | 37| render | string | 是 | 渲染类型，仅支持“canvas”。 | 38| loop | boolean \| number | 否 | 动画播放结束后，是否循环播放，默认值true。值类型为number，且大于等于1时为设置的重复播放的次数。 | 39| autoplay | boolean | 否 | 是否自动播放动画，默认值true。 | 40| name | string | 否 | 开发者自定义的动画名称，后续支持通过该名称引用控制动画，默认为空。 | 41| initialSegment | [number, number] | 否 | 指定动画播放的起始帧号，指定动画播放的结束帧号。 | 42 43 44## lottie.destroy 45 46destroy(name: string): void 47 48销毁动画，页面退出时，必须调用。可配合Canvas组件生命周期接口使用，比如onDisappear()与onPageHide()。 49 50**参数：** 51 52| 参数 | 类型 | 必填 | 描述 | 53| ---- | ------ | ---- | ---------------------------------------- | 54| name | string | 是 | 被指定的动画名，同loadAnimation接口参数name, 缺省时销毁所有动画。 | 55 56**示例：** 57 ```ts 58 // xxx.ets 59 import lottie from '@ohos/lottieETS' 60 61 @Entry 62 @Component 63 struct Index { 64 private controller: CanvasRenderingContext2D = new CanvasRenderingContext2D() 65 private animateName: string = "animate" 66 private animatePath: string = "common/lottie/data.json" 67 private animateItem: any = null 68 69 onPageHide(): void { 70 console.log('onPageHide') 71 lottie.destroy() 72 } 73 74 build() { 75 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 76 Canvas(this.controller) 77 .width('30%') 78 .height('20%') 79 .backgroundColor('#0D9FFB') 80 .onReady(() => { 81 console.log('canvas onAppear'); 82 this.animateItem = lottie.loadAnimation({ 83 container: this.controller, 84 renderer: 'canvas', 85 loop: true, 86 autoplay: true, 87 name: this.animateName, 88 path: this.animatePath, 89 }) 90 }) 91 92 Animator('__lottie_ets') // declare Animator('__lottie_ets') when use lottie 93 Button('load animation') 94 .onClick(() => { 95 if (this.animateItem != null) { 96 this.animateItem.destroy() 97 this.animateItem = null 98 } 99 this.animateItem = lottie.loadAnimation({ 100 container: this.controller, 101 renderer: 'canvas', 102 loop: true, 103 autoplay: true, 104 name: this.animateName, 105 path: this.animatePath, 106 initialSegment: [10, 50], 107 }) 108 }) 109 110 Button('destroy animation') 111 .onClick(() => { 112 lottie.destroy(this.animateName) 113 this.animateItem = null 114 }) 115 } 116 .width('100%') 117 .height('100%') 118 } 119 } 120 ``` 121 122  123 124 125## lottie.play 126 127play(name: string): void 128 129播放指定动画。 130 131**参数：** 132 133| 参数 | 类型 | 必填 | 描述 | 134| ---- | ------ | ---- | ---------------------------------------- | 135| name | string | 是 | 被指定的动画名, 同loadAnimation接口参数name，缺省时播放所有动画。 | 136 137**示例：** 138 139 ```ts 140 lottie.play(this.animateName) 141 ``` 142 143 144## lottie.pause 145 146pause(name: string): void 147 148暂停指定动画，下次调用lottie.play()从当前帧开始。 149 150**参数：** 151 152| 参数 | 类型 | 必填 | 描述 | 153| ---- | ------ | ---- | ---------------------------------------- | 154| name | string | 是 | 被指定的动画名，同loadAnimation接口入参name，缺省时暂停所有动画。 | 155 156**示例：** 157 158 ```ts 159 lottie.pause(this.animateName) 160 ``` 161 162 163## lottie.togglePause 164 165togglePause(name: string): void 166 167暂停或播放指定动画，等效于lottie.play()与lottie.pause()切换调用。 168 169**参数：** 170 171| 参数 | 类型 | 必填 | 描述 | 172| ---- | ------ | ---- | ---------------------------------------- | 173| name | string | 是 | 被指定的动画名，同loadAnimation接口参数name，缺省时停止所有动画。 | 174 175**示例：** 176 177 ```ts 178 lottie.togglePause(this.animateName) 179 ``` 180 181 182## lottie.stop 183 184stop(name: string): void 185 186停止指定动画，下次调用lottie.play()从第一帧开始。 187 188**参数：** 189 190| 参数 | 类型 | 必填 | 描述 | 191| ---- | ------ | ---- | ---------------------------------------- | 192| name | string | 是 | 被指定的动画名，同loadAnimation接口参数name，缺省时停止所有动画。 | 193 194**示例：** 195 196 ```ts 197 lottie.stop(this.animateName) 198 ``` 199 200 201## lottie.setSpeed 202 203setSpeed(speed: number, name: string): void 204 205设置指定动画播放速度。 206 207**参数：** 208 209| 参数 | 类型 | 必填 | 描述 | 210| ----- | ------ | ---- | ---------------------------------------- | 211| speed | number | 是 | 值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0/-1.0正常速度播放。 | 212| name | string | 是 | 被指定的动画，同loadAnimation接口参数name，缺省时停止所有动画。 | 213 214**示例：** 215 216 ```ts 217 lottie.setSpeed(5, this.animateName) 218 ``` 219 220 221## lottie.setDirection 222 223setDirection(direction: AnimationDirection, name: string): void 224 225设置指定动画播放顺序。 226 227**参数：** 228 229| 参数 | 类型 | 必填 | 描述 | 230| --------- | ------------------ | ---- | ---------------------------------------- | 231| direction | AnimationDirection | 是 | 1为正向，-1为反向; 当设置为反向时，从当前播放进度开始回播直到首帧，loop值为true时可无限倒放；speed<0叠加时也是倒放。<br/>AnimationDirection：1 \| -1 | 232| name | string | 是 | 被指定的动画名，同loadAnimation接口参数name，缺省时设置所有动画方向。 | 233 234**示例：** 235 236 ```ts 237 lottie.setDirection(-1, this.animateName) 238 ``` 239 240 241## AnimationItem 242 243loadAnimation接口的返回对象，具有属性与接口。属性描述如下： 244 245| 参数名称 | 参数类型 | 参数描述 | 246| ----------------- | ---------------------------------------- | ---------------------------------------- | 247| name | string | 动画名称。 | 248| isLoaded | boolean | 动画是否已加载。 | 249| currentFrame | number | 当前播放的帧号, 默认精度为>=0.0的浮点数, 调用setSubframe(false)后精度为去小数点后的正整数。 | 250| currentRawFrame | number | 当前播放帧数, 精度为>=0.0的浮点数。 | 251| firstFrame | number | 当前播放片段的第一帧帧号。 | 252| totalFrames | number | 当前播放片段的总帧数。 | 253| frameRate | number | 帧率 (frame/s)。 | 254| frameMult | number | 帧率 (frame/ms)。 | 255| playSpeed | number | 值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0 \| -1.0正常速度播放。 | 256| playDirection | number | 播放方向, 1为正放, -1为倒放。 | 257| playCount | number | 动画完成播放的次数。 | 258| isPaused | boolean | 当前动画是否已暂停, 值为true动画已暂停。 | 259| autoplay | boolean | 加载动画后是否自动播放, 若值为false需要再调用play()接口开始播放。 | 260| loop | boolean \| number | 类型为boolean时是否循环播放, 类型为number时播放次数。 | 261| renderer | any | 动画渲染对象, 根据渲染类型而定。 | 262| animationID | string | 动画ID。 | 263| timeCompleted | number | 当前动画片段完成单次播放的帧数, 受AnimationSegment设置影响, 与totalFrames属性值相同。 | 264| segmentPos | number | 当前动画片段序号, 值为>=0的正整数。 | 265| isSubframeEnabled | boolean | 关联了currentFrame的精度是否为浮点数。 | 266| segments | AnimationSegment \| AnimationSegment[] | 当前动画的播放片段。 | 267 268 269## AnimationItem.play 270 271play(name?: string): void 272 273播放动画。 274 275**参数：** 276 277| 参数 | 类型 | 必填 | 描述 | 278| ---- | ------ | ---- | --------------- | 279| name | string | 否 | 被指定的动画名，缺省默认为空。 | 280 281**示例：** 282 283 ```ts 284 this.animateItem.play() 285 ``` 286 287 288## AnimationItem.destroy 289 290destroy(name?: string): void 291 292销毁动画。 293 294**参数：** 295 296| 参数 | 类型 | 必填 | 描述 | 297| ---- | ------ | ---- | --------------- | 298| name | string | 否 | 被指定的动画名，缺省默认为空。 | 299 300**示例：** 301 302 ```ts 303 this.animateItem.destroy() 304 ``` 305 306 307## AnimationItem.pause 308 309pause(name?: string): void 310 311暂停动画，下次调用play接口从当前帧开始播放。 312 313**参数：** 314 315| 参数 | 类型 | 必填 | 描述 | 316| ---- | ------ | ---- | --------------- | 317| name | string | 否 | 被指定的动画名，缺省默认为空。 | 318 319**示例：** 320 321 ```ts 322 this.animateItem.pause() 323 ``` 324 325 326## AnimationItem.togglePause 327 328togglePause(name?: string): void 329 330暂停或播放动画，等效于play接口与pause接口之间轮换调用。 331 332**参数：** 333 334| 参数 | 类型 | 必填 | 描述 | 335| ---- | ------ | ---- | --------------- | 336| name | string | 否 | 被指定的动画名，缺省默认为空。 | 337 338**示例：** 339 340 ```ts 341 this.animateItem.togglePause() 342 ``` 343 344 345## AnimationItem.stop 346 347stop(name?: string): void 348 349停止动画，下次调用play接口从第一帧开始播放。 350 351**参数：** 352 353| 参数 | 类型 | 必填 | 描述 | 354| ---- | ------ | ---- | --------------- | 355| name | string | 否 | 被指定的动画名，缺省默认为空。 | 356 357**示例：** 358 359 ```ts 360 this.animateItem.stop() 361 ``` 362 363 364## AnimationItem.setSpeed 365 366setSpeed(speed: number): void 367 368设置动画播放速度。 369 370**参数：** 371 372| 参数 | 类型 | 必填 | 描述 | 373| ----- | ------ | ---- | ---------------------------------------- | 374| speed | number | 是 | 值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0 \| -1.0正常速度播放。 | 375 376**示例：** 377 378 ```ts 379 this.animateItem.setSpeed(5); 380 ``` 381 382 383## AnimationItem.setDirection 384 385setDirection(direction: AnimationDirection): void 386 387设置动画播放顺序。 388 389**参数：** 390 391| 参数 | 类型 | 必填 | 描述 | 392| --------- | ------------------ | ---- | ---------------------------------------- | 393| direction | AnimationDirection | 是 | 1为正向，-1为反向; 当设置为反向时，从当前播放进度开始回播直到首帧，loop值为true时可无限倒放；speed<0叠加时也是倒放。<br/>AnimationDirection：1 \| -1。 | 394 395**示例：** 396 397 ```ts 398 this.animateItem.setDirection(-1) 399 ``` 400 401 402## AnimationItem.goToAndStop 403 404goToAndStop(value: number, isFrame?: boolean): void 405 406设置动画停止在指定帧或时间进度。 407 408**参数：** 409 410| 参数 | 类型 | 必填 | 描述 | 411| ------- | ------- | ---- | ---------------------------------------- | 412| value | number | 是 | 帧号(值大于等于0)或时间进度(ms)。 | 413| isFrame | boolean | 否 | true: 按指定帧控制，false:按指定时间控制，缺省默认false。 | 414| name | string | 否 | 被指定的动画名，缺省默认为空。 | 415 416**示例：** 417 418 ```ts 419 // 按帧号控制 420 this.animateItem.goToAndStop(25, true) 421 // 按时间进度控制 422 this.animateItem.goToAndStop(300, false, this.animateName) 423 ``` 424 425 426## AnimationItem.goToAndPlay 427 428goToAndPlay(value: number, isFrame: boolean, name?: string): void 429 430设置动画从指定帧或时间进度开始播放。 431 432**参数：** 433 434| 参数 | 类型 | 必填 | 描述 | 435| ------- | ------- | ---- | ---------------------------------------- | 436| value | number | 是 | 帧号(值大于等于0)或时间进度(ms) | 437| isFrame | boolean | 是 | true：按指定帧控制， false：按指定时间控制，缺省默认false。 | 438| name | string | 否 | 被指定的动画名，缺省默认为空。 | 439 440**示例：** 441 442 ```ts 443 // 按帧号控制 444 this.animateItem.goToAndPlay(25, true) 445 // 按时间进度控制 446 this.animateItem.goToAndPlay(300, false, this.animateName) 447 ``` 448 449 450## AnimationItem.playSegments 451 452playSegments(segments: AnimationSegment | AnimationSegment[], forceFlag: boolean): void 453 454设置动画仅播放指定片段。 455 456**参数：** 457 458| 参数 | 类型 | 必填 | 描述 | 459| --------- | ---------------------------------------- | ---- | ---------------------------------------- | 460| segments | AnimationSegment = [number, number] \| AnimationSegment[] | 是 | 片段或片段列表；<br/>如果片段列表全部播放完毕后，下轮循环播放仅播放最后一个片段 | 461| forceFlag | boolean | 是 | true：即时生效播放，false：延迟到下轮循环播放再生效 | 462 463**示例：** 464 465 ```ts 466 // 指定播放片段 467 this.animateItem.playSegments([10, 20], false) 468 // 指定播放片段列表 469 this.animateItem.playSegments([[0, 5], [20, 30]], true) 470 ``` 471 472 473## AnimationItem.resetSegments 474 475resetSegments(forceFlag: boolean): void 476 477重置动画播放片段，播放全帧。 478 479**参数：** 480 481| 参数 | 类型 | 必填 | 描述 | 482| --------- | ------- | ---- | ------------------------------ | 483| forceFlag | boolean | 是 | true：即时生效播放，false：延迟到下轮循环播放再生效 | 484 485**示例：** 486 487 ```ts 488 this.animateItem.resetSegments(true) 489 ``` 490 491 492## AnimationItem.resize 493 494resize(): void 495 496刷新动画布局。 497 498**示例：** 499 500 ```ts 501 this.animateItem.resize() 502 ``` 503 504 505## AnimationItem.setSubframe 506 507setSubframe(useSubFrame: boolean): void 508 509设置属性currentFrame的精度显示浮点数。 510 511**参数：** 512 513| 参数 | 类型 | 必填 | 描述 | 514| ------------ | ------- | ---- | ---------------------------------------- | 515| useSubFrames | boolean | 是 | currentFrame属性默认显示浮点数，该接口参数将影响currentFrame属性的精度。<br/>true：属性currentFrame显示浮点。<br/>false：属性currentFrame去浮点数显示整数。 | 516 517**示例：** 518 519 ```ts 520 this.animateItem.setSubframe(false) 521 ``` 522 523 524## AnimationItem.getDuration 525 526getDuration(inFrames?: boolean): void 527 528获取动画单次完整播放的时间(与播放速度无关)或帧数, 与Lottie.loadAnimation接口入参initialSegment有关。 529 530**参数：** 531 532| 参数 | 类型 | 必填 | 描述 | 533| -------- | ------- | ---- | ---------------------------------------- | 534| inFrames | boolean | 否 | true：获取帧数， false：获取时间(单位ms)，缺省默认false。 | 535 536**示例：** 537 538 ```ts 539 this.animateItem.getDuration(true) 540 ``` 541 542 543## AnimationItem.addEventListener 544 545addEventListener<T = any>(name: AnimationEventName, callback: AnimationEventCallback<T>): () => void 546 547添加侦听事件, 事件完成后会触发指定回调函数。返回可删除该侦听事件的函数对象。 548 549**参数：** 550 551| 参数 | 类型 | 必填 | 描述 | 552| -------- | ------------------------------- | ---- | ---------------------------------------- | 553| name | AnimationEventName | 是 | 指定动画事件类型，Lottie内置动画事件类型AnimationEventName：<br/>'enterFrame'、'loopComplete'、'complete'、'segmentStart'、'destroy'、'config_ready'、'data_ready'、'DOMLoaded'、'error'、'data_failed'、'loaded_images' | 554| callback | AnimationEventCallback<T> | 是 | 用户自定义回调函数 | 555 556**示例：** 557 558 ```ts 559 private callbackItem: any = function() { 560 console.log("grunt loopComplete") 561 } 562 let delFunction = this.animateItem.addEventListener('loopComplete', this.animateName) 563 564 // 删除侦听 565 delFunction() 566 ``` 567 568 569## AnimationItem.removeEventListener 570 571removeEventListener<T = any>(name: AnimationEventName, callback?: AnimationEventCallback<T>): void 572 573删除侦听事件。 574 575**参数：** 576 577| 参数 | 类型 | 必填 | 描述 | 578| -------- | ------------------------------- | ---- | ---------------------------------------- | 579| name | AnimationEventName | 是 | 指定动画事件类型，Lottie内置动画事件类型AnimationEventName：<br/>'enterFrame'、'loopComplete'、'complete'、'segmentStart'、'destroy'、'config_ready'、'data_ready'、'DOMLoaded'、'error'、'data_failed'、'loaded_images' | 580| callback | AnimationEventCallback<T> | 否 | 用户自定义回调函数；缺省为空时，删除此事件的所有回调函数。 | 581 582**示例：** 583 584 ```ts 585 this.animateItem.removeEventListener('loopComplete', this.animateName) 586 ``` 587 588 589## AnimationItem.triggerEvent 590 591triggerEvent<T = any>(name: AnimationEventName, args: T): void 592 593直接触发指定事件的所有已设置的回调函数。 594 595**参数：** 596 597| 参数 | 类型 | 必填 | 描述 | 598| ---- | ------------------ | ---- | --------- | 599| name | AnimationEventName | 是 | 指定动画事件类型 | 600| args | any | 是 | 用户自定义回调参数 | 601 602**示例：** 603 604 ```ts 605 private triggerCallBack: any = function(item) { 606 console.log("trigger loopComplete, name:" + item.name) 607 } 608 609 this.animateItem.addEventListener('loopComplete', this.triggerCallBack) 610 this.animateItem.triggerEvent('loopComplete', this.animateItem) 611 this.animateItem.removeEventListener('loopComplete', this.triggerCallBack) 612 ``` 613
