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