OpenHarmony UI动画-lottie

简介

lottie是一个适用于OpenHarmony的动画库，它可以解析Adobe After Effects软件通过Bodymovin插件导出的json格式的动画，并在移动设备上进行本地渲染。

下载安裝

 ohpm install @ohos/lottie

OpenHarmony ohpm 环境配置等更多内容，请参考如何安装 OpenHarmony ohpm 包

使用说明

前提：数据准备

lottie动画文件是由设计人员使用Adobe After Effects软件通过bodymovin插件导出json格式的文件。

AE软件创建动画时需要设置动画的宽(w)、高(h)、bodymovin插件的版本号(v)、帧率(fr)、开始帧(ip)、

结束帧(op)、静态资源信息(assets)、图层信息(layers)等重要信息。

如果仅是用于demo测试，可以使用工程示例中的json文件 。

1.在相应的类中引入组件：

import lottie from '@ohos/lottie'

2.构建渲染上下文

  private mainRenderingSettings: RenderingContextSettings = new RenderingContextSettings(true)
  private mainCanvasRenderingContext: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.mainRenderingSettings)

3.將动画需要的json文件放到pages同级别目录下，然后引用。(json路径为entry/src/main/ets/common/lottie/data.json)

注意：json文件路径不能使用 ./ 或者 .../ 等相对路径，相对路径获取不到动画源数据，会导致动画加载不出来,

传递给loadAnimation 方法的路径是相对于pages父文件夹为基准的，而index页面内引入的相对路径的动画是以index.ets文件为基准的，两者基准不一致。

所以如果json文件放置在pages文件夹下，路径应为 'pages/common/data.json' 样式

  private path:string = "common/lottie/data.json"
  或
  private jsonData:string = {"v":"4.6.6","fr":24,"ip":0,"op":72,"w":1000,"h":1000,"nm":"Comp 2","ddd":0,"assets":[],...}

4.关联画布

       Canvas(this.mainCanvasRenderingContext)
        .width('50%')
        .height(360 + 'px')
        .backgroundColor(Color.Gray)
        .onReady(()=>{
        //抗锯齿的设置
            this.mainCanvasRenderingContext.imageSmoothingEnabled = true;
            this.mainCanvasRenderingContext.imageSmoothingQuality = 'medium'
        })

• 注意：canvas设置的宽高比例建议和动画json资源里面的宽高比例一致，如：json动画资源里的宽高比例是 1:2 ，则canvas设置的宽高也是 1:2

• 想要的抗锯齿效果：mainCanvasRenderingContext.imageSmoothingEnabled = true 与 mainCanvasRenderingContext.imageSmoothingQuality = 'medium'

• 动画绘制前会对canvas画布进行清空处理，画布清空后再绘制动画。

• 5.加载动画

• 加载动画的时机需要注意，点击按钮加载动画可按照正常逻辑放在点击事件内，如果想要实现进入页面自动播放动画，需要结合Canvas组件的onReady()生命回调周期实现，加载动画时机需放置在onReady()生命周期回调内或及之后。

• 同一Canvas组件加载多次/不同动画资源，需要手动销毁动画(lottie.destroy()/animationItem.destroy())，之后才可再次加载其他动画资源。

    this.animationItem?.destroy('2016'); //加载动画前先销毁之前加载的动画
    this.animationItem = lottie.loadAnimation({
            container: this.mainCanvasRenderingContext,  // 渲染上下文
            renderer: 'canvas',                          // 渲染方式
            loop: true,                                  // 是否循环播放,默认true
            autoplay: true,                              // 是否自动播放，默认true
            name: '2016',                                // 动画名称
            contentMode: 'Contain',                      // 填充的模式
            frameRate: 30,                               //设置animator的刷帧率为30
            path: this.path,                             // json路径
            initialSegment: [10,50]                      // 播放的动画片段
          })
     或      
    lottie.loadAnimation({
            container: this.mainCanvasRenderingContext,  // 渲染上下文
            renderer: 'canvas',                          // 渲染方式
            loop: true,                                  // 是否循环播放,默认true
            autoplay: true,                              // 是否自动播放，默认true
            contentMode: 'Contain',                      // 填充的模式
            frameRate: 30,                               //设置animator的刷帧率为30
            animationData: this.jsonData,                // json对象数据
            initialSegment: [10,50]                      // 播放的动画片段
          })
  

• 加载动画时，path 参数和 animationData 参数，二者选其一。

• path 参数：只支持加载entry/src/main/ets 文件夹下的相对路径，不支持跨包查找文件。

• animationData 参数：可结合ResourceManager进行读取资源文件内容进行设置。

• 加载外部资源图片：应用默认读取沙箱路径下的图片，如果沙箱下没有对应的资源图片，则会继续读取rawfile下的对应资源图片

6.HSP场景

• 为了适配HSP场景，loadAnimation接口新增当前场景上下文context可选参数传入，在HSP场景下需要传正确的context，非HSP场景不影响，context可以不传

    let contexts = getContext(this).createModuleContext('library') as common.UIAbilityContext;
    lottie.loadAnimation({
            container: this.mainCanvasRenderingContext,  // 渲染上下文
            renderer: 'canvas',                          // 渲染方式
            loop: true,                                  // 是否循环播放,默认true
            autoplay: true,                              // 是否自动播放，默认true
            animationData: this.jsonData,                // json对象数据
            context: contexts,                           // 当前场景上下文context
            contentMode: 'Contain',                      // 填充的模式
            initialSegment: [10,50]                      // 播放的动画片段
          })
  

• 在HSP场景下，lottie加载动画json资源文件需通过animationData方式加载，需把动画json资源文件放在rawfile下进行读取加载：

• 加载动画时，animationData 参数。

• animationData 参数：可结合ResourceManager进行读取资源文件内容进行设置。

    let resStr = new util.TextDecoder('utf-8',{ignoreBOM: true});
    let context = getContext(this).createModuleContext('library') as common.UIAbilityContext
    context.resourceManager.getRawFile('grunt.json',(err: Error,data: Uint8Array) =>{
      if(data === null || data === undefined || data.buffer=== undefined){
        return;
      }
      let lottieStr = resStr.decode(new Uint8Array(data.buffer));
      this.jsonData = JSON.parse(lottieStr);
    })
  

7.控制动画

• 播放动画

  lottie.play() //所有动画播放
  或
  animationItem.play() //当前指定animationItem动画播放
  

• 停止动画

  lottie.stop() //所有动画停止
  或
  animationItem.stop() //当前指定animationItem动画停止
  

• 暂停动画

  lottie.pause() //所有动画暂停
  或
  animationItem.pause() //当前指定animationItem动画暂停
  

• 切换暂停/播放

  lottie.togglePause() //所有动画切换暂停/播放
  或
  animationItem.togglePause() //当前指定animationItem动画切换暂停/播放
  

• 设置播放速度

  注意：speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0/-1.0正常速度播放

  lottie.setSpeed(1) //所有动画设置播放速度
  或
  animationItem.setSpeed(1) //当前指定animationItem动画设置播放速度
  

• 设置动画播放方向

  注意：direction 1为正向，-1为反向

  lottie.setDirection(1) //所有动画设置播放方向
  或
  animationItem.setDirection(1) //当前指定animationItem动画设置播放方向
  

• 销毁动画

  注意：页面不显示或退出页面时，需要销毁动画; 可配合页面生命周期aboutToDisappear()及onPageHide(),或者Canvas组件的onDisAppear()使用

  lottie.destroy() //所有动画播放
  或
  animationItem.destroy() //当前指定animationItem动画播放
  

• 控制动画停止在某一帧或某一时刻

  注意：根据第二个参数判断按帧还是按毫秒控制，true 按帧控制，false 按时间控制，缺省默认为false

  animationItem.goToAndStop(250,true)
  或
  animationItem.goToAndStop(5000,false)
  

• 控制动画从某一帧或某一时刻开始播放

  注意:根据第二参数判断按帧还是按毫秒控制，true 按帧控制，false 按时间控制，缺省默认为false

  animationItem.goToAndPlay(250,true)
  或
  animationItem.goToAndPlay(12000,false)
  

• 限定动画资源播放时的整体帧范围，即设置动画片段

  animationItem.setSegment(5,15);
  

• 播放动画片段

  注意：第二参数值为true立刻生效, 值为false循环下次播放的时候生效

  animationItem.playSegments([5,15],[20,30],true)
  

• 重置动画播放片段，使动画从起始帧开始播放完整动画

  注意：参数值为true立刻生效, 值为false循环下次播放的时候生效

  animationItem.resetSegments(5,15);
  

• 获取动画时长/帧数

  注意：参数值为true时获取帧数，值为false时获取时间(单位ms)

  animationItem.getDuration();
  

• 添加侦听事件

  注意：添加和移除的事件监听，回调函数需是同一个，需预先定义，否则将不能正确移除

  AnimationEventName = 'enterFrame' | 'loopComplete' | 'complete' | 'segmentStart' | 'destroy' | 'config_ready' | 'data_ready' | 'DOMLoaded' | 'error' | 'data_failed' | 'loaded_images';
  
  animationItem.addEventListener("enterFrame",function(){
      // TODO something
  })
  

• 更改动画渲染颜色

  注意：第一个参数颜色是RGB值，第二个参数是动画的层次 可不填，第三个参数是对应动画层次的元素的下标值 可不填

  animateItem.changeColor([255,150,203])  //修改整个动画的颜色
  或
  animateItem.changeColor([255,150,203],2) //修改该动画第二层的颜色
  或
  animateItem.changeColor([255,150,203],2,2) //修改该动画第二层第二个元素的颜色
  

• 移除侦听事件

  animationItem.removeEventListener("enterFrame",function(){
      // TODO something
  })
  

• 刷新动画布局

  animationItem.resize()
  

• 动画填充模式

  注意：动画填充模式共有5种：Fill,Cover,Top,Bottom,Contain，其中默认的填充模式是：Contain

  animateItem.setContentMode('Cover');
  

• 设置动画的刷帧率

  注意：设置动画animator的刷帧率，范围是1~120

  animateItem.setFrameRate(30);
  

• lottie销毁动画支持以下两种方式：

1. lottie.destroy：销毁所有动画播放，lottie.destroy(name)销毁指定name的动画。
2. animateItem.destroy：销毁指定animateItem的动画播放。

注意：当同一个页面中存在多个动画，且动画实例赋值给同一个变量animateItem时，使用animateItem.destroy销毁动画时，只会销毁最后一个。如：

    this.animationItem = lottie.loadAnimation({
          container: this.mainCanvasRenderingContext,  // 渲染上下文
          renderer: 'canvas',                          // 渲染方式
          loop: true,                                  // 是否循环播放,默认true
          autoplay: true,                              // 是否自动播放，默认true
          name: 'cat',                                // 动画名称
          contentMode: 'Contain',                      // 填充的模式
          path: this.path,                             // json路径
          initialSegment: [10,50]                      // 播放的动画片段
        })
        
    this.animationItem = lottie.loadAnimation({
          container: this.mainCanvasRenderingContext,  // 渲染上下文
          renderer: 'canvas',                          // 渲染方式
          loop: true,                                  // 是否循环播放,默认true
          autoplay: true,                              // 是否自动播放，默认true
          name: '2016',                                // 动画名称
          contentMode: 'Contain',                      // 填充的模式
          path: this.path,                             // json路径
          initialSegment: [10,50]                      // 播放的动画片段
        })        

执行this.animationItem.destroy()，只会销毁name为2016的动画，name为cat的动画不会被销毁。建议：动画销毁时，使用lottie.destroy方式进行销毁。

接口说明

使用方法	类型	相关描述
play()	name?	播放
stop()	name?	停止
pause()	name?	暂停
togglePause()	name?	切换暂停
destroy()	name?	销毁动画
goToAndStop()	value, isFrame?, name?	跳到某一时刻并停止
goToAndPlay()	value, isFrame?, name?	跳到某一时刻并播放
setSegment()	init,end	设置动画片段
playSegments()	arr, forceFlag	播放指定片段
resetSegments()	forceFlag	重置动画
setSpeed()	speed	设置播放速度
setDirection()	direction	设置播放方向
getDuration()	isFrames?	获取动画时长
addEventListener()	eventName,callback	添加监听状态
removeEventListener()	name,callback?	移除监听状态
changeColor()	color, layer?, index?	更改动画颜色
setContentMode()	contentMode	设置填充模式
setFrameRate()	frameRate	设置动画刷帧率

新增特性

1. 支持canvas渲染模式下动画的颜色修改

• 支持设置RGG格式颜色
• 支持设置RGBA格式颜色
• 支持设置起始关键帧颜色

2. 支持canvas渲染模式下动画的masks/mattes部分特性

• masks模式支持 mode = a, mode = s, mode = f 模式
• mattes模式支持 tt = 1, tt = 2 模式

3. 支持canvas渲染模式下动画的高斯模糊效果

4. 支持canvas渲染模式下加载外部资源图片

• 支持加载沙箱路径的外部资源图片(优先查找的路径)
• 支持加载rawfile目录下的外部资源图片

5. 支持设置填充模式

• Fill 填充拉伸(可能被拉伸、不会被裁剪)
• Top 等比填充-顶对齐(不会被裁剪、长边对齐)
• Bottom 等比填充-底对齐(不会被裁剪、长边对齐)
• Cover 等比缩放填充(可能被裁剪、断边对齐)
• Contain 等比填充-纵向中对齐(不会被裁剪、长边对齐)

6. 支持设置动画animator的刷帧率

约束与限制

在下述版本验证通过：

• DevEco Studio: NEXT Developer Beta1(5.0.3.122), SDK: API12(5.0.0.18)

目录结构

/lottie        # 项目根目录
├── entry      # 示例代码文件夹
├── lottie     # lottie库文件夹
│    └─ src/main/js
│       └─ build/player 
│          └─ lottie.js # 核心代码，包含json解析，动画绘制，操作动画
│       └─index.d.ts    # 接口声明文档                     
├── README.md  # 安装使用方法