更新记录

0.0.1（2026-10-28）

✨ 首次发布

平台兼容性

uni-app(4.73)

uni-app x(4.72)

其他

ant-lottie Lottie动画组件

Lottie 动画组件，一套 API 多端运行，兼容 H5、微信/支付宝小程序、App(Android/iOS/鸿蒙) 以及 uni-app x。内置各端 Lottie 运行时，无需再执行 npm install 安装 lottie 相关依赖。

特性

• 🌈 多端统一：<ant-lottie> 一个标签，全端渲染（Web SVG / 小程序 Canvas2d / App 原生引擎）
• 🎬 播放控制：播放、暂停、停止、跳转（帧/进度）、循环、自动播放、速度、方向
• 📡 事件监听：complete、loopComplete、segmentStart、enterFrame*、destroy
• 📦 开箱即用：Web 与小程序端已内置 lottie 运行时
• 🍎 原生渲染：uni-app x 的 App 端使用原生 Lottie 引擎（lottie-android / lottie-ios / lottie-turbo）

* enterFrame 仅 Web 与小程序端支持，App 原生端出于性能考虑未逐帧回调。

平台兼容

快速上手

基础用法

<ant-lottie src="https://example.com/animation.json" l-style="height:200px"></ant-lottie>

通过 ref 控制

<view style="height:200px">
    <ant-lottie ref="lottieRef" src="/static/lottie/heart.json"></ant-lottie>
</view>
<button @click="play">播放</button>
<button @click="pause">暂停</button>
<button @click="destroy">销毁</button>

const lottieRef = ref(null)
const play = () => lottieRef.value?.play()
const pause = () => lottieRef.value?.pause()
const destroy = () => lottieRef.value?.destroy()

动态加载动画

方式一：ref 调用 loadAnimation，返回 AntLottie 实例：

<view style="height:200px">
    <ant-lottie ref="lottieRef"></ant-lottie>
</view>
<button @click="loadAndPlay">加载并播放</button>

const loadAndPlay = async () => {
    const lottie = await lottieRef.value?.loadAnimation('https://example.com/animation.json')
    lottie.setSpeed(2)
    lottie.play()
}

方式二：通过 loaded 事件获取 loadAnimation 函数：

<view style="height:200px">
    <ant-lottie @loaded="onLoaded" @complete="onComplete"></ant-lottie>
</view>

let loadAnimation = null
const onLoaded = (fn) => { loadAnimation = fn }
const onComplete = () => { console.log('播放完成') }

// 任意时机调用
const lottie = await loadAnimation('/static/lottie/heart.json')
lottie.addEventListener('loopComplete', () => { console.log('一次循环结束') })

直接传入动画数据

<ant-lottie :frames="animationData" :loop="true" :autoplay="true" :speed="1.5"></ant-lottie>

快速预览

导入插件后，直接使用以下标签可查看内置示例动画：

<ant-lottie-demo />

API

Props

Events

组件方法（通过 ref 调用）

AntLottie 实例方法

通过 loadAnimation 的返回值或 ready 事件获得：

AnimationEventName 可选值：enterFrame（仅Web/小程序）、loopComplete、complete、segmentStart、destroy

使用说明与注意事项

1. 组件高度：组件默认撑满父容器，请通过 l-style 或父容器为组件指定高度。
2. 小程序端 src 仅支持 http(s) 网络地址或 frames 传入动画数据；本地路径请使用 frames。
3. App 端本地 /static 动画由插件自动读取并传入渲染层，无需额外处理。
4. uni-app x 的 App 端（Android/iOS/鸿蒙）需使用自定义基座运行；首次编译需在 HBuilderX 中制作自定义基座。
5. 鸿蒙端使用 @ohos/lottie-turbo 渲染，在模拟器上较大的动画文件可能出现卡顿，建议真机测试。
6. 动态切换动画：各端均支持对同一组件多次调用 loadAnimation 加载不同动画；鸿蒙端以真机表现为准。
7. Vue2 项目无需安装 composition-api，组件基于 Options API 实现，vue2/vue3 均可直接使用。

目录结构

ant-lottie
├── common                  # 内置 lottie 运行时（Web/小程序端）
├── components
│   ├── ant-lottie          # 组件源码（.vue 为 uni-app，.uvue 为 uni-app x）
│   └── ant-lottie-demo     # 快速预览示例
├── utssdk
│   ├── app-android         # Android 原生实现 (lottie-android)
│   ├── app-ios             # iOS 原生实现 (lottie-ios)
│   └── app-harmony         # 鸿蒙原生实现 (lottie-turbo)
├── changelog.md
├── readme.md
└── THIRD-PARTY-NOTICES.md  # 第三方库版权声明

第三方引擎

本插件基于以下优秀的开源引擎封装，版权声明详见 THIRD-PARTY-NOTICES.md：

• lottie-web (MIT)
• lottie-miniprogram (MIT)
• lottie-android (Apache-2.0)
• lottie-ios (Apache-2.0)
• lottie_turbo (Apache-2.0)