本文记录了在HarmonyOS 6.1项目中集成Lottie动画的完整过程包括依赖配置、资源管理、Canvas渲染以及常见错误的排查方法。适合正在开发HarmonyOS应用的开发者参考。 目录前言Lottie简介与优势环境准备依赖配置详解rawfile资源管理Canvas渲染实战常见错误排查最佳实践总结一、前言在HarmonyOS应用开发中动画是提升用户体验的重要元素。Lottie作为一个跨平台的动画库能够直接渲染After Effects导出的动画极大地提高了开发效率。本文将详细介绍如何在HarmonyOS 6.1中正确集成和使用Lottie。开发环境HarmonyOS版本6.1DevEco Studio最新版本Lottie版本2.0.31语言ArkTS二、Lottie简介与优势什么是LottieLottie是Airbnb开源的一个动画库可以解析Adobe After Effects导出的动画JSON文件并在移动端实时渲染。核心优势设计师友好设计师可以直接使用AE制作复杂动画文件小JSON格式体积远小于GIF或视频可交互支持动态控制播放、暂停、速度等跨平台iOS、Android、Web、HarmonyOS均支持高质量矢量动画任意分辨率都清晰三、依赖配置详解3.1 添加Lottie依赖在项目的entry/oh-package.json5中添加依赖{name:entry,version:1.0.0,description:Please describe the basic information.,main:,author:,license:,dependencies:{ohos/lottie:^2.0.0}}3.2 安装依赖在项目根目录执行ohpminstall注意事项确保网络连接正常如果安装失败尝试清理缓存ohpm cache clean检查ohpm版本是否为最新3.3 验证安装安装成功后会在oh_modules/.ohpm/目录下看到ohoslottie2.0.31文件夹。四、rawfile资源管理4.1 资源目录结构HarmonyOS中Lottie动画JSON文件需要放在rawfile目录下entry/src/main/resources/ └── rawfile/ └── lottie/ ├── success.json ├── failed.json └── loading.json重要提示rawfile是原始资源目录文件会原样打包到应用中路径大小写敏感不要在路径前加斜杠/4.2 正确的路径写法❌错误写法privateanimatePath:string/lottie/failed.json;// 前导斜杠会导致加载失败✅正确写法privateanimatePath:stringlottie/failed.json;// 相对于rawfile目录4.3 获取Lottie动画资源方式一LottieFiles官网访问https://lottiefiles.com/搜索需要的动画如success, error, loading下载JSON格式文件放入rawfile/lottie/目录方式二AE导出如果有设计师配合可以直接从After Effects导出Lottie JSON。五、Canvas渲染实战5.1 基础使用示例在自定义对话框中使用Lottie动画importlottie,{AnimationItem}fromohos/lottie;CustomDialogexportstruct GameOverDialog{privateanimateName:stringgameOver;privateanimatePath:stringlottie/failed.json;// 注意无前导斜杠privatecontext:CanvasRenderingContext2DnewCanvasRenderingContext2D();privateanimateItem?:AnimationItem;controller:CustomDialogController;build(){Column(){Text(游戏结束).fontSize(22).margin({top:30,bottom:30})// Canvas组件承载Lottie动画Canvas(this.context).width(120).height(120).backgroundColor(Color.Transparent).onReady((){// 加载并播放动画this.animateItemlottie.loadAnimation({container:this.context,renderer:canvas,loop:true,autoplay:true,name:this.animateName,path:this.animatePath,})})Button(重新开始).onClick((){this.controller.close()})}}}5.2 关键参数说明lottie.loadAnimation({container:this.context,// Canvas上下文必填renderer:canvas,// 渲染器类型HarmonyOS使用canvasloop:true,// 是否循环播放autoplay:true,// 是否自动播放name:animationName,// 动画唯一标识用于控制path:lottie/animation.json// 动画文件路径相对rawfile})5.3 控制动画播放// 播放动画lottie.play(this.animateName)// 暂停动画lottie.pause(this.animateName)// 停止动画lottie.stop(this.animateName)// 销毁动画释放资源lottie.destroy(this.animateName)5.4 生命周期管理CustomDialogexportstruct AnimationDialog{privateanimateName:stringmyAnimation;privateanimateItem?:AnimationItem;// 对话框显示时播放onPageShow(){lottie.play(this.animateName)}// 对话框隐藏时暂停onPageHide(){lottie.pause(this.animateName)}// 对话框销毁时释放资源aboutToDisappear(){lottie.destroy(this.animateName)}}六、常见错误排查6.1 错误Cannot find module ‘ohos/lottie’错误信息ERROR: Cannot find module ohos/lottie or its corresponding type declarations.原因分析依赖未安装或安装失败oh-package.json5配置错误解决方案# 1. 清理缓存ohpm cache clean# 2. 重新安装依赖ohpminstall# 3. 检查oh-package.json5中是否正确添加依赖{dependencies:{ohos/lottie:^2.0.0}}6.2 错误Failed to get rawfile错误信息Failed to get rawfile GetAsset failed: lottie/failed.json原因分析动画文件路径错误最常见文件不存在或路径不对解决方案✅检查路径格式// 错误带前导斜杠privateanimatePath:string/lottie/failed.json;// 正确相对路径privateanimatePath:stringlottie/failed.json;✅检查文件位置确保文件在正确的目录entry/src/main/resources/rawfile/lottie/failed.json6.3 错误Lottie canvas indeterminate attached错误信息Coordinator canvas(33) indeterminate attached or not, treat it as attached.原因分析Canvas组件的生命周期管理问题通常不影响功能。解决方案确保Canvas在onReady回调中初始化Canvas(this.context).onReady((){// 在这里初始化Lottiethis.animateItemlottie.loadAnimation({...})})6.4 动画不显示可能原因Canvas尺寸为0动画文件损坏路径错误排查步骤Canvas(this.context).width(120)// 确保有明确的宽度.height(120)// 确保有明确的高度.backgroundColor(#FFCCCC)// 临时设置背景色以检查Canvas是否显示.onReady((){console.info(Canvas ready)// 添加日志this.animateItemlottie.loadAnimation({container:this.context,renderer:canvas,loop:true,autoplay:true,name:this.animateName,path:this.animatePath,})console.info(Lottie loaded)// 添加日志})七、最佳实践7.1 资源管理建议的目录结构resources/rawfile/ ├── lottie/ │ ├── ui/ # UI相关动画 │ │ ├── loading.json │ │ └── success.json │ ├── game/ # 游戏相关动画 │ │ ├── win.json │ │ └── lose.json │ └── effects/ # 特效动画 │ └── particle.json7.2 性能优化1. 及时销毁动画aboutToDisappear(){if(this.animateItem){lottie.destroy(this.animateName)this.animateItemundefined}}2. 控制动画质量对于复杂动画可以适当降低尺寸Canvas(this.context).width(100)// 根据实际需求调整.height(100)3. 避免同时播放过多动画同时播放多个Lottie动画会影响性能建议限制同屏动画数量非活动状态时暂停动画7.3 代码封装创建Lottie组件封装Componentexportstruct LottieAnimation{PropanimationPath:stringPropwidth:number100Propheight:number100Proploop:booleantruePropautoplay:booleantrueprivatecontext:CanvasRenderingContext2DnewCanvasRenderingContext2D()privateanimateItem?:AnimationItemprivateanimateName:stringlottie_${Date.now()}build(){Canvas(this.context).width(this.width).height(this.height).backgroundColor(Color.Transparent).onReady((){this.animateItemlottie.loadAnimation({container:this.context,renderer:canvas,loop:this.loop,autoplay:this.autoplay,name:this.animateName,path:this.animationPath,})})}aboutToDisappear(){if(this.animateItem){lottie.destroy(this.animateName)}}}// 使用示例LottieAnimation({animationPath:lottie/success.json,width:120,height:120})八、总结本文详细介绍了在HarmonyOS 6.1中集成Lottie动画的完整流程包括关键要点回顾依赖配置在oh-package.json5中添加ohos/lottie依赖资源管理动画文件放在rawfile目录路径不带前导斜杠Canvas渲染使用Canvas组件承载Lottie动画生命周期及时销毁动画释放资源错误排查路径问题是最常见的错误适用场景✅ 加载动画✅ 成功/失败反馈✅ 空状态页面✅ 引导动画✅ 游戏特效注意事项动画文件不宜过大建议100KB复杂动画可能影响性能及时释放资源避免内存泄漏参考资料HarmonyOS官方文档Lottie官网LottieFiles资源库作者简介HarmonyOS开发者专注于跨平台移动应用开发。本文示例代码项目源码如果本文对你有帮助欢迎点赞、收藏、关注