Lottie

About 29 min

Lottie

说明: 从 API Version 8 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

Lottie为三方开源库,依赖Canvas与RenderingContext。

权限列表

导入模块

import lottie from 'lottie-web'
1

说明: 'lottie-web' 名字以实际生态发布后的命名为准。

lottie.loadAnimation

loadAnimation(

path: string, container: object, render: string, loop: boolean, autoplay: boolean, name: string ): AnimationItem

加载动画,须提前声明Animator('__lottie_ets')对象,并在Canvas完成布局后调用。可配合Canvas组件生命周期接口使用,比如onAppear()与onPageShow()。

  • 参数

    参数

    类型

    必填

    描述

    path

    string

    hap包内动画资源文件路径,仅支持json格式。示例:path: "common/lottie/data.json"

    container

    object

    canvas绘图上下文,声明范式需提前声明CanvasRenderingContext2D。

    render

    string

    渲染类型,仅支持“canvas”。

    loop

    boolean | number

    动画播放结束后,是否循环播放,默认值true。值类型为number,且大于等于1时为设置的重复播放的次数。

    autoplay

    boolean

    是否自动播放动画,默认值true。

    name

    string

    开发者自定义的动画名称,后续支持通过该名称引用控制动画,默认为空。

    initialSegment

    [number, number]

    指定动画播放的起始帧号,指定动画播放的结束帧号。

lottie.destroy

destroy(name: string): void

销毁动画,页面退出时,必须调用。可配合Canvas组件生命周期接口使用,比如onDisappear()与onPageHide()。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,同loadAnimation接口参数name, 缺省时销毁所有动画。

  • 示例

    import lottie from 'lottie-web'
    
    @Entry
    @Component
    struct Index {
      private controller: CanvasRenderingContext2D = new CanvasRenderingContext2D()
      private animateName: string = "animate"
      private animatePath: string = "common/lottie/data.json"
      private animateItem: any = null
    
      private onPageHide(): void {
        console.log('onPageHide')
        lottie.destroy()
      }
    
      build() {
        Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
          Canvas(this.controller)
          .width('30%')
          .height('20%')
          .backgroundColor('#0D9FFB')
          .onAppear(() => {
            console.log('canvas onAppear');
            this.animateItem = lottie.loadAnimation({
              container: this.controller,
              renderer: 'canvas',
              loop: true,
              autoplay: true,
              name: this.animateName,
              path: this.animatePath,
            })
          })
    
          Animator('__lottie_ets') // declare Animator('__lottie_ets') when use lottie
          Button('load animation')
            .onClick(() => {
            if (this.animateItem != null) {
              this.animateItem.destroy()
              this.animateItem = null
            }
            this.animateItem = lottie.loadAnimation({
              container: this.controller,
              renderer: 'canvas',
              loop: true,
              autoplay: true,
              name: this.animateName,
              path: this.animatePath,
              initialSegment: [10, 50],
            })
          })
    
          Button('destroy animation')
            .onClick(() => {
              lottie.destroy(this.animateName)
              this.animateItem = null
            })
        }
        .width('100%')
        .height('100%')
      }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61

lottie.play

play(name: string): void

播放指定动画。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名, 同loadAnimation接口参数name,缺省时播放所有动画。

  • 示例

    lottie.play(this.animateName)
    
    1

lottie.pause

pause(name: string): void

暂停指定动画,下次调用lottie.play()从当前帧开始。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,同loadAnimation接口入参name,缺省时暂停所有动画。

  • 示例

    lottie.pause(this.animateName)
    
    1

lottie.togglePause

togglePause(name: string): void

暂停或播放指定动画,等效于lottie.play()与lottie.pause()切换调用。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,同loadAnimation接口参数name,缺省时停止所有动画。

  • 示例

    lottie.togglePause(this.animateName)
    
    1

lottie.stop

stop(name: string): void

停止指定动画,下次调用lottie.play()从第一帧开始。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,同loadAnimation接口参数name,缺省时停止所有动画。

  • 示例

    lottie.stop(this.animateName)
    
    1

lottie.setSpeed

setSpeed(speed: number, name: string): void

设置指定动画播放速度。

  • 参数

    参数

    类型

    必填

    描述

    speed

    number

    值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0/-1.0正常速度播放。

    name

    string

    被指定的动画,同loadAnimation接口参数name,缺省时停止所有动画。

  • 示例

    lottie.setSpeed(5, this.animateName)
    
    1

lottie.setDirection

setDirection(direction: AnimationDirection, name: string): void

设置指定动画播放顺序。

  • 参数

    参数

    类型

    必填

    描述

    direction

    AnimationDirection

    1为正向,-1为反向; 当设置为反向时,从当前播放进度开始回播直到首帧,loop值为true时可无限倒放;speed<0叠加时也是倒放。

    AnimationDirection:1 | -1

    name

    string

    被指定的动画名,同loadAnimation接口参数name,缺省时设置所有动画方向。

  • 示例

    lottie.setDirection(-1, this.controlName)
    
    1

AnimationItem

loadAnimation接口的返回对象,具有属性与接口。属性描述如下:

参数名称

参数类型

参数描述

name

string

动画名称。

isLoaded

boolean

动画是否已加载。

currentFrame

number

当前播放的帧号, 默认精度为>=0.0的浮点数, 调用setSubframe(false)后精度为去小数点后的正整数。

currentRawFrame

number

当前播放帧数, 精度为>=0.0的浮点数。

firstFrame

number

当前播放片段的第一帧帧号。

totalFrames

number

当前播放片段的总帧数。

frameRate

number

帧率 (frame/s)。

frameMult

number

帧率 (frame/ms)。

playSpeed

number

值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0 | -1.0正常速度播放。

playDirection

number

播放方向, 1为正放, -1为倒放。

playCount

number

动画完成播放的次数。

isPaused

boolean

当前动画是否已暂停, 值为true动画已暂停。

autoplay

boolean

加载动画后是否自动播放, 若值为false需要再调用play()接口开始播放。

loop

boolean | number

类型为boolean时是否循环播放, 类型为number时播放次数。

renderer

any

动画渲染对象, 根据渲染类型而定。

animationID

string

动画ID。

timeCompleted

number

当前动画片段完成单次播放的帧数, 受AnimationSegment设置影响, 与totalFrames属性值相同。

segmentPos

number

当前动画片段序号, 值为>=0的正整数。

isSubframeEnabled

boolean

关联了currentFrame的精度是否为浮点数。

segments

AnimationSegment | AnimationSegment[]

当前动画的播放片段。

AnimationItem.play

play(name?: string): void

播放动画。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,缺省默认为空。

  • 示例

    this.anim.play()
    
    1

AnimationItem.destroy

destroy(name?: string): void

销毁动画。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,缺省默认为空。

  • 示例

    this.anim.destroy()
    
    1

AnimationItem.pause

pause(name?: string): void

暂停动画,下次调用play接口从当前帧开始播放。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,缺省默认为空。

  • 示例

    this.anim.pause()
    
    1

AnimationItem.togglePause

togglePause(name?: string): void

暂停或播放动画,等效于play接口与pause接口之间轮换调用。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,缺省默认为空。

  • 示例

    this.anim.togglePause()
    
    1

AnimationItem.stop

stop(name?: string): void

停止动画,下次调用play接口从第一帧开始播放。

  • 参数

    参数

    类型

    必填

    描述

    name

    string

    被指定的动画名,缺省默认为空。

  • 示例

    this.anim.stop()
    
    1

AnimationItem.setSpeed

setSpeed(speed: number): void

设置动画播放速度。

  • 参数

    参数

    类型

    必填

    描述

    speed

    number

    值为浮点类型, speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0 | -1.0正常速度播放。

  • 示例

    this.anim.setSpeed(5);
    
    1

AnimationItem.setDirection

setDirection(direction: AnimationDirection): void

设置动画播放顺序。

  • 参数

    参数

    类型

    必填

    描述

    direction

    AnimationDirection

    1为正向,-1为反向; 当设置为反向时,从当前播放进度开始回播直到首帧,loop值为true时可无限倒放;speed<0叠加时也是倒放。

    AnimationDirection:1 | -1。

  • 示例

    this.anim.setDirection(-1)
    
    1

AnimationItem.goToAndStop

goToAndStop(value: number, isFrame: boolean): void

设置动画停止在指定帧或时间进度。

  • 参数

    参数

    类型

    必填

    描述

    value

    number

    帧号(值大于等于0)或时间进度(ms)。

    isFrame

    boolean

    true: 按指定帧控制,false:按指定时间控制,缺省默认false。

    name

    string

    被指定的动画名,缺省默认为空。

  • 示例

    // 按帧号控制
    this.anim.goToAndStop(25, true)
    // 按时间进度控制
    this.anim.goToAndStop(300, false, this.animateName)
    
    1
    2
    3
    4

AnimationItem.goToAndPlay

goToAndPlay(value: number, isFrame: boolean): void

设置动画从指定帧或时间进度开始播放。

  • 参数

    参数

    类型

    必填

    描述

    value

    number

    帧号(值大于等于0)或时间进度(ms)

    isFrame

    boolean

    true:按指定帧控制, false:按指定时间控制,缺省默认false。

    name

    string

    被指定的动画名,缺省默认为空。

  • 示例

    // 按帧号控制
    this.anim.goToAndPlay(25, true)
    // 按时间进度控制
    this.anim.goToAndPlay(300, false, this.animateName)
    
    1
    2
    3
    4

AnimationItem.playSegments

playSegments(segments: AnimationSegment | AnimationSegment[], forceFlag: boolean): void

设置动画仅播放指定片段。

  • 参数

    参数

    类型

    必填

    描述

    segments

    AnimationSegment = [number, number] | AnimationSegment[]

    片段或片段列表;

    如果片段列表全部播放完毕后,下轮循环播放仅播放最后一个片段

    forceFlag

    boolean

    true:即时生效播放,false:延迟到下轮循环播放再生效

  • 示例

    // 指定播放片段
    this.anim.playSegments([10, 20], false)
    // 指定播放片段列表
    this.anim.playSegments([[0, 5], [20, 30]], true)
    
    1
    2
    3
    4

AnimationItem.resetSegments

resetSegments(forceFlag: boolean): void

重置动画播放片段,播放全帧。

  • 参数

    参数

    类型

    必填

    描述

    forceFlag

    boolean

    true:即时生效播放,false:延迟到下轮循环播放再生效

  • 示例

    this.anim.resetSegments(true)
    
    1

AnimationItem.resize

resize(): void

刷新动画布局。

  • 示例

    this.anim.resize()
    
    1

AnimationItem.setSubframe

setSubframe(useSubFrame: boolean): void

设置属性currentFrame的精度显示浮点数。

  • 参数

    参数

    类型

    必填

    描述

    useSubFrames

    boolean

    currentFrame属性默认显示浮点数,该接口参数将影响currentFrame属性的精度。

    true:属性currentFrame显示浮点。

    false:属性currentFrame去浮点数显示整数。

  • 示例

    this.anim.setSubframe(false)
    
    1

AnimationItem.getDuration

getDuration(inFrames?: boolean): void

获取动画单次完整播放的时间(与播放速度无关)或帧数, 与Lottie.loadAnimation接口入参initialSegment有关。

  • 参数

    参数

    类型

    必填

    描述

    inFrames

    boolean

    true:获取帧数, false:获取时间(单位ms),缺省默认false。

  • 示例

    this.anim.setSubframe(true)
    
    1

AnimationItem.addEventListener

addEventListener<T = any>(name: AnimationEventName, callback: AnimationEventCallback<T>): () => void

添加侦听事件, 事件完成后会触发指定回调函数。返回可删除该侦听事件的函数对象。

  • 参数

    参数

    类型

    必填

    描述

    name

    AnimationEventName

    指定动画事件类型,Lottie内置动画事件类型AnimationEventName:

    'enterFrame'、'loopComplete'、'complete'、'segmentStart'、'destroy'、'config_ready'、'data_ready'、'DOMLoaded'、'error'、'data_failed'、'loaded_images'

    callback

    AnimationEventCallback<T>

    用户自定义回调函数

  • 示例

    private callbackItem: any = function() {
        console.log("grunt loopComplete")
    }
    let delFunction = this.animateItem.addEventListener('loopComplete', this.callbackItem)
    
    // 删除侦听
    delFunction()
    
    1
    2
    3
    4
    5
    6
    7

AnimationItem.removeEventListener

removeEventListener<T = any>(name: AnimationEventName, callback?: AnimationEventCallback<T>): void

删除侦听事件。

  • 参数

    参数

    类型

    必填

    描述

    name

    AnimationEventName

    指定动画事件类型,Lottie内置动画事件类型AnimationEventName:

    'enterFrame'、'loopComplete'、'complete'、'segmentStart'、'destroy'、'config_ready'、'data_ready'、'DOMLoaded'、'error'、'data_failed'、'loaded_images'

    callback

    AnimationEventCallback<T>

    用户自定义回调函数;缺省为空时, 删除此事件的所有回调函数。

  • 示例

    this.animateItem.removeEventListener('loopComplete', this.callbackItem)
    
    1

AnimationItem.triggerEvent

triggerEvent<T = any>(name: AnimationEventName, args: T): void

直接触发指定事件的所有已设置的回调函数。

  • 参数

    参数

    类型

    必填

    描述

    name

    AnimationEventName

    指定动画事件类型

    args

    any

    用户自定义回调参数

  • 示例

    private triggerCallBack: any = function(item) {
        console.log("trigger loopComplete, name:" + item.name)
    }
    
    this.animateItem.addEventListener('loopComplete', this.triggerCallBack)
    this.animateItem.triggerEvent('loopComplete', this.animateItem)
    this.animateItem.removeEventListener('loopComplete', this.triggerCallBack)
    
    1
    2
    3
    4
    5
    6
    7