# LottieC **Repository Path**: Louis-C7/lottie-c ## Basic Information - **Project Name**: LottieC - **Description**: lottie是一个适用于OpenHarmony的动画库，它可以解析Adobe After Effects软件通过Bodymovin插件导出的json格式的动画，并在移动设备上进行本地渲染。该库基于rlottie及c++实现 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 17 - **Created**: 2025-02-07 - **Last Updated**: 2025-02-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # lottieC ## 简介 lottieC是一个适用于OpenHarmony的动画库，它可以解析Adobe After Effects软件通过Bodymovin插件导出的json格式的动画，并在移动设备上进行本地渲染。 ![showlottie](./screenshot/showlottie.gif) (待定) ## 下载安裝 ``` ohpm install @ohos/lottieC (待定) ``` OpenHarmony ohpm 环境配置等更多内容，请参考[如何安装 OpenHarmony ohpm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md) ## 快速上手 ### 示例 ``` import { LottieView, LottieController, LottieListener, lottie } from '@ohos/lottiec'; @Entry @Component struct Index { @State cacheKeyOne:string = 'animation1' //缓存键 private controller: LottieController = new LottieController(); //动画控制器 private listener: LottieListener | null = new LottieListener({ onEnterFrame: (args: ESObject) => { //播放帧回调 this.updateAllStates() }, onLoopComplete: (args: ESObject) => { //动画播放完毕后回调 console.info("lottie complete"); this.playCount = this.controller?.playCount; this.totalPlayedCount += 1; }, onDestroy: (args: ESObject) => { //动画删除后回调 console.info("lottie destroy"); }, onDOMLoaded: (args: ESObject) => { //动画加载完成，播放之前触发回调 this.totalPlayedCount = 0; this.updateAllStates(); }, }) build() { ... LottieView({ loop: true, //循环 autoplay: true, //自动播放 name: '2016', //定义动画名 contentMode: 'Contain', //填充模式 path: "common/lottie/data.json", //动画路径 controller: this.controller, //动画控制器 cacheKey: this.cacheKeyOne, //缓存键 listener: this.listener //监听事件容器 }) Button("播放") .onClick(() => { this.controller.play(); }) Button("暂停") .onClick(() => { this.controller.pause(); }) Button("销毁") .onClick(() => { this.controller.destroy(); }) ... } // 页面销毁时释放动画资源 aboutToDisappear(): void { console.info('aboutToDisappear'); lottie.destroy(); } } ``` ### 注意事项 - 1.建议在页面销毁或卸载时，将页面上所有的动画进行销毁，确保页面资源得到妥善管理和释放。 (待补充) ## 使用说明 前提：数据准备 lottie动画文件是由设计人员使用Adobe After Effects软件通过bodymovin插件导出json格式的文件。 AE软件创建动画时需要设置动画的宽(w)、高(h)、bodymovin插件的版本号(v)、帧率(fr)、开始帧(ip)、 结束帧(op)、静态资源信息(assets)、图层信息(layers)等重要信息。 如果仅是用于demo测试，可以使用[工程示例中的json文件](待补充) 。(待定) 1.引入组件： ``` import lottie from '@ohos/lottieC' ``` 2.动画资源位置 (待定)將动画需要的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":[],...} ``` 3.使用组件 参考快速上手中示例 4.控制动画 - 播放动画 ``` lottie.play() //所有动画播放 或 lottie.play('animation1') //animation1动画播放 或 this.controller.play() //this.controller绑定的动画播放 ``` - 停止动画 ``` lottie.stop() //所有动画停止 或 lottie.stop('animation1') //animation1动画停止 或 this.controller.stop() //this.controller绑定的动画停止 ``` - 暂停动画 ``` lottie.pause() //所有动画暂停 或 lottie.pause('animation1') //animation1动画暂停 或 this.controller.pause() //this.controller绑定的动画暂停 ``` - 切换暂停/播放 ``` lottie.togglePause() //所有动画切换暂停/播放 或 lottie.togglePause('animation1') //animation1动画切换暂停/播放 或 this.controller.togglePause() //this.controller绑定的动画切换暂停/播放 ``` - 设置播放速度 > 注意：speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0/-1.0正常速度播放 ``` lottie.setSpeed(1) //所有动画设置播放速度 或 lottie.setSpeed(1,'animation1') //animation1动画设置播放速度 或 this.controller.setSpeed(1) //this.controller绑定的动画设置播放速度 ``` - 设置动画播放方向 > 注意：direction 1为正向，-1为反向 ``` lottie.setDirection(1) //所有动画设置播放方向 或 lottie.setDirection(1,'animation1') //animation1动画设置播放方向 或 this.controller.setDirection(1) ///this.controller绑定的动画设置播放方向 ``` - 销毁动画 > 注意：页面不显示或退出页面时，需要销毁动画; 可配合页面生命周期aboutToDisappear()及onPageHide() ``` lottie.destroy() //销毁所有动画 或 lottie.destroy('animation1') //销毁animation1动画 或 this.controller.destroy('animation1') //销毁指定name动画 ``` - 控制动画停止在某一帧或某一时刻 > 注意：根据第二个参数判断按帧还是按毫秒控制，true 按帧控制，false 按时间控制，缺省默认为false ``` this.controller.goToAndStop(250,true) 或 this.controller.goToAndStop(5000,false) ``` - 控制动画从某一帧或某一时刻开始播放 > 注意:根据第二参数判断按帧还是按毫秒控制，true 按帧控制，false 按时间控制，缺省默认为false ``` this.controller.goToAndPlay(250,true) 或 this.controller.goToAndPlay(12000,false) ``` - 限定动画资源播放时的整体帧范围，即设置动画片段 ``` this.controller.setSegment(5,15); ``` - 播放动画片段 > 注意：第二参数值为true立刻生效, 值为false循环下次播放的时候生效 ``` this.controller.playSegments([5,15],[20,30],true) ``` - 重置动画播放片段，使动画从起始帧开始播放完整动画 > 注意：参数值为true立刻生效, 值为false循环下次播放的时候生效 ``` this.controller.resetSegments(5,15); ``` - 获取动画时长/帧数 > 注意：参数值为true时获取帧数，值为false时获取时间(单位ms) ``` this.controller.getDuration(); ``` - 添加侦听事件 > 注意：添加和移除的事件监听，回调函数需是同一个，需预先定义，否则将不能正确移除 ``` AnimationEventName = 'enterFrame' | 'loopComplete' | 'complete' | 'segmentStart' | 'destroy' | 'config_ready' | 'data_ready' | 'DOMLoaded' | 'error' | 'data_failed' | 'loaded_images'; this.controller.addEventListener('loopComplete', (args: Object): void => { console.info("loopComplete"); }) ``` - 更改动画渲染颜色 > 注意：第一个参数颜色是RGB值，第二个参数是动画的层次 可不填，第三个参数是对应动画层次的元素的下标值 可不填 ``` this.controller.changeColor([255,150,203]) //修改整个动画的颜色 或 this.controller.changeColor([255,150,203],2) //修改该动画第二层的颜色 或 this.controller.changeColor([255,150,203],2,2) //修改该动画第二层第二个元素的颜色 ``` - 移除侦听事件 ``` this.controller.removeEventListener('loopComplete') ``` - 刷新动画布局 ``` this.controller.resize(200, 200) ``` - 动画填充模式 > 注意：动画填充模式共有5种：Fill,Cover,Top,Bottom,Contain，其中默认的填充模式是：Contain ``` this.controller.setContentMode('Fill'); ``` - 设置动画的刷帧率 > 注意：设置动画animator的刷帧率，范围是1~120 帧率越大，功耗越严重 ``` this.controller.setFrameRate(30); ``` - 清除缓存文件 > 注意：container是与canvas组件绑定的上下文CanvasRenderingContext2D,用于本地资源路径json文件 ``` lottie.clearFileCache() //清除所有动画缓存文件 或 lottie.clearFileCache('https://p3-dcd.byteimg.com/obj/motor-mis-img/5ec2c8af22bc17aedafe147a1d38f21d.json') //清除指定动画缓存文件 或 lottie.clearFileCache('common/lottie/data_url.json') //清除指定本地动画中网络资源缓存文件 ``` 5.HSP场景 - 在HSP场景下，lottie加载动画json资源文件需通过animationData方式加载，需把动画json资源文件放在rawfile下进行读取加载： ``` LottieView({ loop: true, //循环 autoplay: true, //自动播放 name: '2016', //定义动画名 contentMode: 'Contain', //填充模式 animationData: this.jsonData, // json对象数据 controller: this.controller, //动画控制器 cacheKey: this.cacheKeyOne, //缓存键 listener: this.listener //监听事件容器 }) ``` - 读取文件部分 ``` 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); }) ``` 6.混淆 - 混淆导致编译报错，请在对应的模块下的obfuscation-rules.txt文件里配置一下：-keep ./oh_modules/@ohos/lottie ，这样就解决使用混淆编译导致的报错 7.判断动画资源是否为网络加载使用示例 ``` this.isNet = '是否为网络加载' + this.animateItem.isNetLoad ``` ## LottieController内接口说明 | 使用方法 | 类型 | 相关描述 | |-----------------------|-----------------------|------------| | play() | name? | 播放 | | stop() | name? | 停止 | | pause() | name? | 暂停 | | togglePause() | name? | 切换暂停 | | destroy() | name? | 销毁动画 | | goToAndStop() | value, isFrame? | 跳到某一时刻并停止 | | goToAndPlay() | value, isFrame? | 跳到某一时刻并播放 | | 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 | 设置动画刷帧率 | ## lottie全局api说明 | 使用方法 | 参数类型 | 相关描述 | |-------------------------|------------------------------------------------------|------------------------------------------------------------------------------------------------------------| | lottie.play() | animationName?: string (动画名) | 播放动画,可通过设置animationName指定动画操作 | | lottie.stop() | animationName?: string (动画名) | 停止动画,可通过设置animationName指定动画操作 | | lottie.pause() | animationName?: string (动画名) | 暂停动画,可通过设置animationName指定动画操作 | | lottie.togglePause() | animationName?: string (动画名) | 切换暂停动画,可通过设置animationName指定动画操作 | | lottie.destroy() | animationName?: string (动画名) | 销毁动画,可通过设置animationName指定动画操作 | | lottie.setSpeed() | speed: number (播放方向) , animationName?: string (动画名) | 全局动画播放方向控制,speed>0正向播放, speed<0反向播放, speed=0暂停播放, speed=1.0/-1.0正常速度播放 | | lottie.setDirection() | direction: 1 或 -1, animationName?: string (动画名) | 全局设置播放方向,可通过设置animationName指定动画操作; 1为正向, -1为反向; 当设置为反向时, 从当前播放进度开始回播直到首帧, loop值为true时可无限倒放, speed<0叠加时也是倒放 | | lottie.clearFileCache() | url?: string (路径path或者网络uri) | 全局文件缓存清除 ,可通过设置url指定清除文件. | | lottie.resizeCache() | size: number (缓存容器大小) | 设置缓存容器大小 | | lottie.clearCache() | | 清空缓存容器 | | lottie.removeCache() | key: string (缓存键) | 通过缓存键移除缓存 | | lottie.containsCache() | key: string (缓存键) | 通过缓存键查询缓存是否存在 返回布尔值 true存在 false不存 | ## 新增特性 (待补充) ## 约束与限制 在下述版本验证通过： - DevEco Studio: DevEco Studio 5.0.1 Release(5.0.5.306), SDK: API13(5.0.1.112) - DevEco Studio: NEXT Developer Beta3(5.0.3.524), SDK: API12(5.0.0.25) ## 目录结构 ```` /lottie-c # 项目根目录 ├── entry # 示例代码文件夹 ├── library # lottie-c库文件夹 │ └─ src/main │ └─ cpp/types │ └─ napi_init.cpp # │ └─ ets │ ├── components # LottieView组件 │ ├── model # 类型定义 │ ├── utils # 工具 │ ├── Lottie.ets # lottieC全局lottie声明 ├── README.md # 安装使用方法 ├── README_zh.md # 安装使用方法 ```` ## 贡献代码 (待补充) ## 开源协议 (待补充) ## 不支持能力 (待补充)