✍️作者简介：小北编程（专注于HarmonyOS、Android、Java、Web、TCP/IP等技术方向） 🐳博客主页： 开源中国、稀土掘金、51cto博客、博客园、知乎、简书、慕课网、CSDN
🔔如果文章对您有一定的帮助请👉关注✨、点赞👍、收藏📂、评论💬。
🔥如需转载请参考【转载须知】
HarmonyOS 开发中使用 Lottie 动画库
一、什么是 Lottie？
简介
Lottie 是由 Airbnb 团队开发并开源的跨平台动画库，支持在 iOS、Android、Web、React Native、Windows 和 HarmonyOS 等平台解析并播放使用 Adobe After Effects 制作、通过 Bodymovin 插件导出的 JSON 动画文件。
推荐使用lottie-turbo：声明式调用更加简洁，支持并行加载、内存缓存、子线程渲染，性能优化30%+，多动画/复杂动画场景下UI界面更流畅。
相比传统的帧动画或手动编写动画代码，Lottie 提供了更轻量、更流畅、更高效的动画解决方案，大幅提升了 UI 表现力和开发效率。
📌 Lottie 官网地址：
airbnb.design/lottie
注意：此地址为官方介绍页面，非 HarmonyOS 使用地址。
二、Lottie 的优势
- 🎨 高保真动画呈现：高度还原设计师在 AE 中的动画设计；
- 📦 资源体积小：相比 GIF 和视频，JSON 动画更轻量；
- 🔁 支持交互与循环：可控制播放、暂停、进度、循环等；
- 🧩 跨平台复用性强：一份动画 JSON 可在多个平台共用；
- ⚡ 性能优越：利用硬件加速渲染，播放流畅资源消耗低。
三、HarmonyOS 中如何使用 Lottie？
在 HarmonyOS ArkTS 项目中，可以通过官方或三方组件 @ohos/lottie 使用 Lottie 动画。
1. 安装依赖
使用命令安装：
bash
ohpm install @ohos/lottie或在 module.json5 中添加依赖：
json
"dependencies": {
"@ohos/lottie": "1.0.0" // 请根据实际版本号填写
}三方包地址（OpenHarmony 官方源）：
🔗 ohpm.openharmony.cn/#/cn/detail...
2. 动画 JSON 文件的放置与使用场景
| 场景 | 放置目录 | 加载方式 | 注意事项 |
|---|---|---|---|
| ✅ 本地加载 | entry/src/main/ets/common |
使用相对路径：common/xxx.json |
推荐开发调试或轻量动画使用 |
| ✅ 网络加载 | - | 直接传入 URL，如 http://... |
需声明权限（见下方） |
| ✅ HSP 加载 | resources/rawfile/ |
使用 $rawfile('xxx.json') |
推荐正式发布使用（资源内置） |
📌 网络资源加载需声明权限：
json
"reqPermissions": [
{ "name": "ohos.permission.INTERNET" },
{ "name": "ohos.permission.GET_NETWORK_INFO" }
]四、ArkTS 示例代码
1. 简单的使用
- 將动画需要的json文件放到pages同级别目录下，然后引用。(json路径为entry/src/main/ets/common/lottie/data.json)
注意：json文件路径不能使用 ./ 或者 .../ 等相对路径，相对路径获取不到动画源数据，会导致动画加载不出来。
2.关联画布
kotlin
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。
3.加载动画
- 加载动画的时机需要注意，点击按钮加载动画可按照正常逻辑放在点击事件内，如果想要实现进入页面自动播放动画，需要结合Canvas组件的onReady()生命回调周期实现，加载动画时机需放置在onReady()生命周期回调内或及之后。
- 同一Canvas组件加载多次/不同动画资源，需要手动销毁动画(lottie.destroy('name'))，之后才可再次加载其他动画资源。
kotlin
lottie.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
imagePath: 'lottie/images/', // 加载读取指定路径下的图片资源
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] // 播放的动画片段
})
或
lottie.loadAnimation({
uri: "https://assets7.lottiefiles.com/packages/lf20_sF7uci.json", // uri网络资源
container: this.canvasRenderingContext, // 渲染上下文
renderer: 'canvas', // canvas 渲染模式
loop: true, // 是否循环播放,默认true
autoplay: true, // 是否自动播放，默认true
name: this.animateName, // 动画名
})五、常用属性说明
| 使用方法 | 类型 | 相关描述 |
|---|---|---|
| play() | name? | 播放 |
| stop() | name? | 停止 |
| pause() | name? | 暂停 |
| togglePause() | name? | 切换暂停 |
| destroy() | name? | 销毁动画 |
在官网说明上有两个使用属性说明AnimationItem 和 LottiePlayer 都属于 HarmonyOS @ohos/lottie 动画库提供的能力，它们各自代表不同的使用层级或场景。下面是它们的区别和使用建议：
🔹 1、概念理解
✅ AnimationItem
是指一个 具体的动画实例 ，通常是通过调用
loadAnimation()返回的对象，对这个对象的操作就是针对某一个动画进行控制。
✅ LottiePlayer
是一个 全局静态控制器或动画管理器，用于从全局角度控制动画播放（如同一个名字的多个实例、当前页面或当前Ability中的动画等），属于更底层或跨组件的控制方式。
🔸 2、区别对比
| 对比项 | AnimationItem |
LottiePlayer |
|---|---|---|
| 📌 代表含义 | 单个 Lottie 动画实例 | 全局/统一的动画控制类 |
| 📦 典型获取方式 | const item = loadAnimation(params) |
直接调用类方法如 LottiePlayer.play() |
| 📍 控制范围 | 控制该实例 | 控制全局、指定 name 的动画 |
| 🔁 支持多个动画控制 | ✅ 支持多个实例独立控制 | ⚠️ 主要支持通过 name 控制已命名动画 |
| 🧩 生命周期管理 | 需手动 destroy() 销毁 |
可全局 destroy(name) |
| ⏱️ 使用场景 | 通常在组件内单独控制 | 多页面、全局统一控制、调试等 |
| 💡 示例调用 | item.play() |
LottiePlayer.play('loading') |
🔸 3、使用建议
| 场景 | 推荐使用 |
|---|---|
| 在组件或页面中局部播放一个动画（如按钮动画、加载动画） | ✅ AnimationItem |
| 需要跨页面统一控制某些动画（如登录页和首页都需播放/销毁同一动画） | ✅ LottiePlayer |
| 想实现同一动画资源的多实例、不同状态控制 | ✅ AnimationItem |
| 使用 canvas 等高级特性，需要关联 context2d | ✅ LottiePlayer |
| 清理缓存、设置全局播放方向、统一帧率等 | ✅ LottiePlayer |
🔹 4、实际开发中的配合使用示例
php
// 加载动画并返回 AnimationItem 实例
const anim = LottiePlayer.loadAnimation({
name: 'loading',
path: $rawfile('loading_animation.json'),
autoplay: true,
loop: true,
container: 'lottieContainer'
})
// 单独控制某个动画实例
anim.setSpeed(1.5)
anim.pause()
anim.goToAndPlay(60)
// 通过 LottiePlayer 全局控制
LottiePlayer.pause('loading') // 控制所有名称为 loading 的动画
LottiePlayer.setSpeed(2.0, 'loading')
LottiePlayer.destroy('loading')🔸 5、总结
| 功能需求 | 使用推荐 |
|---|---|
| 控制单个动画实例 | AnimationItem（面向对象） |
| 控制多个命名动画或全局状态 | LottiePlayer（面向服务） |
| 涉及 canvas / context2D 联动 | LottiePlayer |
| 与组件生命周期强绑定 | AnimationItem |
| 动画复用、缓存管理等系统级控制 | LottiePlayer |
六、开发建议与注意事项
- ✅ 建议使用
$rawfile()加载正式动画资源，避免路径错误； - ⚠️ 动画文件不要过大，否则影响首屏加载时间；
- ✅ 提前压缩优化 JSON，可减少解析开销；
- ❗ 注意平台兼容性差异，复杂动画请在目标设备测试；
- ⚙️ 控制频繁动画销毁和复用，避免内存泄露。
七、总结
Lottie 为 HarmonyOS 开发者带来了极大的动画表现力提升，不仅能减少前端动画开发工作量，更能与设计师协作无缝衔接。通过合理使用 Lottie，开发者可以在应用中打造更出色的用户体验。
🎯 如果你正在开发启动页动画、加载动效、空页面占位动画、按钮反馈动画等，Lottie 都是一个极具性价比的方案！
📁 三种资源放置方式建议
| 场景 | 是否推荐 | 放置路径 | 说明 |
|---|---|---|---|
| ✅ 正式发布使用（推荐） | ★★★★☆ | resources/rawfile/ |
使用 $rawfile('xxx.json')，系统自动打包，路径可靠 |
| ✅ 本地资源 | ★★★☆☆ | entry/src/main/ets/common |
可快速修改、无需打包，但路径易错 |
| ✅ 加载网络资源 | ★★★☆☆ | 无需本地目录 | 支持远程 CDN，适用于动画变动频繁场景，但依赖网络、需授权权限 |
仓库地址
OpenHarmony三方库：ohpm.openharmony.cn/#/cn/detail...
OpenHarmony源码地址：gitcode.com/openharmony...
👍 点赞，是我创作的动力！ ⭐️ 收藏，是我努力的指引！ ✏️ 评论，是我进步的宝藏！ 💖 衷心感谢你的阅读以及支持！
本文使用 文章同步助手 同步