三方库的基本使用

三方库是开发者对系统能力的封装和拓展，可以实现代码复用，提升开发效率。

一、三方库的获取

        1、访问Gitee开源社区

        在Gitee中，搜索OpenHarmony-TPC仓库，在tpc_resource中对三方库进行了资源汇总，可以供开发者参考。可通过扫码获取地址。Gitee三方库链接地址

        2、OpenHarmony三方库中心仓

        进入OpenHarmony三方库中心仓，根据类型或者直接搜索寻找需要的三方库。可通过扫码获取地址。OpenHarmony三方库中心仓

二、三方库分类

        常用的三方库可以分为UI、动画、网络、图片、多媒体、数据存储、安全、工具等。

        1、Gitee中三方库分类概览

• UI库：
  • @ohos/textlayoutbuilder：可以定制任一样式的文本构建工具，包括字体间距、大小、颜色、富文本高亮显示等。
  • @ohos/roundedimageview：可以生成圆角矩形、或者椭圆形等图片形状。

• 网络库：
  • @ohos/axios：可以运行在node.js 和浏览器中，基于Axios 原库v1.3.4版本进行适配，并沿用其现有用法和特性。
• 动画库：
  • @ohos/lottie：可以解析Adobe After Effects软件通过Bodymovin插件导出的json格式的动画，并在移动设备上进行本地渲染。
  • @ohos/svg：可以解析SVG图片并渲染到页面上。

三、三方库使用实例（@ohos/lottie） 

        1、安装ohpm

        OHPM CLI 作为鸿蒙生态三方库的包管理工具，支持OpenHarmony共享包的发布、安装和依赖管理。在HarmonyOS开发官网搜索“ohpm使用指导”，根据电脑的配置，选择安装合适的ohpm。

        （1）下载ohpm工具包

                ohpm下载链接地址

        （2）初始化ohpm

                解压文件，进入“ohpm/bin”目录，打开命令行工具，执行如下指令初始化ohpm

                注：初始化ohpm前，需先完成node.js环境变量配置。

                        注意文件路径：D:\commandline-tools-windows-2.0.0.2\command-line-tools\ohpm\bin，一定要是ohpm下的bin

                Windows环境下执行：

init.bat

                Linux/macOS环境下执行：

./init

        （3）将ohpm配置到环境变量中 

                 Windows环境：在此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量中，将ohpm命令行工具的bin目录配置到系统或者用户的PATH变量中；

                macOS环境：打开终端工具，执行以下命令

export OHPM_HOME=/home/xx/Downloads/ohpm  #本处路径请替换为ohpm的安装路径
export PATH=${OHPM_HOME}/bin:${PATH}

        （4）检测安装是否成功 

ohpm -v

        终端输出为版本号（如：0.6.10），则表示安装成功。

        其他配置，参考ohpm指导 

 2、@ohos/lottie是什么

        @ohos/lottie是基于lottie-web开发，集成在三方库社区内的开源版本，是HarmonyOS系统中复杂动画的一种解决方案。

        动画是传达想法和创造更好的用户交互体验的工具，常见使用动画的场景如下：

• 启动动画：APP logo动画的播放。
• 加载动画：网络请求的loading动画。
• 上下拉刷新动画：请求更多资源时的刷新动画。
• 按钮动画：切换按钮、编辑按钮、播放按钮等按钮的切换过渡动画。
• 视图转场动画：一些场景的转场添加动画能够提升用户体验。

        @ohos/lottie提供了使用JSON动画文件的解决方案，开发者可以在原生应用中像使用静态图像一样使用动画，而不用关注动画的实现过程，并且@ohos/lottie具有一套完整的API控制动画的行为，可以让动画更具有交互性。接下来将介绍@ohos/lottie的安装和基本使用。

3、@ohos/lottie的安装与卸载

        （1）安装@ohos/lottie

        通过ohpm执行对应的指令，将lottie安装到项目中。

ohpm install @ohos/lottie

        （2）卸载@ohos/lottie

        通过ohpm执行卸载指令，将lottie从项目中删除，其程序包和配置信息将会从项目中移除。

ohpm uninstall @ohos/lottie

        4、使用@ohos/lottie 

        （1）@ohos/lottie的引入

        通过import指令在项目中引入@ohos/lottie到文件中。

import lottie from '@ohos/lottie'

        （2） 构建Canvas画布

        @ohos/lottie解析JSON动画文件的数据需要基于Canvas 画布进行2D渲染，所以在加载JSON动画之前，要先初始化渲染上下文，并在画面中创建Canvas画布区域，将对应的渲染上下文renderingContext传递给Canvas。

// 初始化渲染上下文  
private renderingSettings: RenderingContextSettings = new RenderingContextSettings(true) // 设置开启抗锯齿
private renderingContext: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.renderingSettings)  // 创建2D渲染上下文
// renderingContext为构建的上下文

        （3）准备JSON文件

        准备JSON文件，即动画的源数据，文件中描述了动画的具体路径。 

        （4）关联画布

// 创建Canvas画布，并绑定renderingContext   
Canvas(this.renderingContext)
  ...

        （5）加载JSON动画

        加载JSON动画需要用到loadAnimation方法，在方法中需配置相应的初始设置，包括渲染上下文、渲染方式以及JSON动画资源的路径等。可以直接使用lottie.loadAnimation方法，也可以用一个animationItem实例来接收返回的animationItem对象。

// 用animationItem实例接收
// 加载动画，传入之前定义的Canvas、上下文、JSON文件
let animationItem = lottie.loadAnimation({
            container: this.renderingContext,            // 渲染上下文
            renderer: 'canvas',                          // 渲染方式
            loop: true,                                  // 是否循环播放,默认true
            autoplay: true,                              // 是否自动播放，默认true
            path: 'common/lottie/data.json',             // json路径
          })     
 
    lottie.loadAnimation({                               // 或者直接使用
            container: this.renderingContext,            // 渲染上下文
            renderer: 'canvas',                          // 渲染方式
            loop: true,                                  // 是否循环播放,默认true
            autoplay: true,                              // 是否自动播放，默认true
            path: 'common/lottie/data.json',             // json路径
          })

        （6）控制动画

        @ohos/lottie内封装了包括状态控制，进度控制，播放设置控制和属性控制等多个API，用户可以利用这些API完成对动画的控制，实现更加灵活的交互效果。 

// 播放、暂停、停止、销毁  可以使用lottie，也可以使用animationItem实例进行控制
lottie.play();        // 从目前停止的帧开始播放
lottie.stop();        // 停止播放，回到第0帧
lottie.pause();       // 暂停该动画，在当前帧停止并保持
lottie.togglePause(); // 切换暂停/播放状态
lottie.destroy();     // 删除该动画，移除相应的元素标签等。在unmount的时候，需要调用该方法

// 播放进度控制
animationItem.goToAndStop(value, isFrame); // 跳到某个时刻/帧并停止。isFrame(默认false)指示value表示帧还是时间(毫秒)
animationItem.goToAndPlay(value, isFrame); // 跳到某个时刻/帧并进行播放
animationItem.goToAndStop(30, true);       // 例：跳转到第30帧并停止
animationItem.goToAndPlay(300);            // 例：跳转到第300毫秒并播放

// 控制帧播放
animationItem.setSegment(5,15);             // 限定动画资源播放时的整体帧范围，即设置动画片段
animationItem.resetSegments(5,15);          // 重置播放的动画片段
animationItem.playSegments(arr, forceFlag); // arr可以包含两个数字或者两个数字组成的数组，forceFlag表示是否立即强制播放该片段
animationItem.playSegments([10,20], false); // 例：播放完之前的片段，播放10-20帧
animationItem.playSegments([[5,15],[20,30]], true); //例： 直接播放5-15帧和20-30帧

// 动画基本属性控制
lottie.setSpeed(speed);         // 设置播放速度，speed为1表示正常速度
lottie.setDirection(direction); // 设置播放方向，1表示正向播放，-1表示反向播放

// 获取动画帧数属性
animationItem.getDuration();    //获取动画时长

        （7）事件订阅 

        在一些特殊场景下，比如开始加载动画或者动画播放结束时，可能需要执行相应的操作，在@ohos/lottie中提供了事件订阅和取消订阅的功能，当触发对应的event，会执行传入的回调函数，用户可以在回调函数中完成要实现的功能。

// 订阅事件
animationItem.addEventListener(event,function(){
    // TODO something
})

// 取消订阅事件
animationItem.removeEventListener(event,function(){
    // TODO something
})

        常见的event事件类型如下：

// event事件类型
'enterFrame'   // 每进入一帧就会触发
'loopComplete' // 当前循环下播放（循环播放/非循环播放）结束时触发
'complete'     // 播放完成时触发
'segmentStart' // 播放指定片段时触发，playSegments、resetSegments等方法刚开始播放指定片段时会发出，如果playSegments播放多个片段，多个片段最开始都会触发。
'destroy'      // 销毁动画时触发
'data_ready'   // 数据准备完成
'DOMLoaded'    // 动画相关dom已经被添加
'error'        // 出现错误
'data_failed'  // 数据加载失败
  ...