登录Vue3 中 Lottie 动画库的使用指南
Lottie 是 Airbnb 开源的一款跨平台动画渲染库，能够将 AE（After Effects）制作的动画导出为 JSON 格式，并在 Web、iOS、Android 等平台无缝渲染，完美还原设计师的动画效果。在 Vue3 项目中集成 Lottie，既能提升页面交互体验，又能避免传统 GIF / 视频动画的性能问题和体积冗余。本文将详细讲解 Vue3 中 Lottie 的安装、基础使用、高级配置及实战技巧。
一、核心优势
在开始集成前，先了解 Lottie 适配 Vue3 项目的核心价值：
- 轻量化：JSON 动画文件体积远小于 GIF / 视频，且支持按需加载；
- 可交互：可通过代码控制动画播放、暂停、跳转、循环等，支持自定义交互逻辑；
- 矢量渲染：动画基于矢量，适配不同分辨率设备无模糊；
- Vue3 友好：支持组合式 API（Setup），可封装为通用组件，复用性强。
二、环境准备与安装
1. 依赖安装
Vue3 项目中推荐使用 lottie-web（官方 Web 端实现），通过 npm/yarn/pnpm 安装：
# npm
npm install lottie-web --save
# yarn
yarn add lottie-web
# pnpm
pnpm add lottie-web
2. 动画资源准备
Lottie 依赖 AE 导出的 JSON 动画文件，获取方式：
- 设计师使用 AE 制作动画，通过
Bodymovin插件导出 JSON 文件； - 从 Lottie 官方素材库获取免费动画：LottieFiles。
将下载的 JSON 动画文件放入 Vue3 项目的 public 或 src/assets 目录（推荐 public，避免打包路径问题）。
三、基础使用：封装通用 Lottie 组件
为了在项目中复用，我们先封装一个通用的 Lottie 组件（支持 Vue3 组合式 API）。
1. 创建 Lottie 通用组件
在 src/components 目录下新建 LottieAnimation.vue：
<template>
<!-- 动画容器，需指定宽高 -->
<div ref="lottieContainer" class="lottie-container" :style="{ width, height }"></div>
</template>
<script setup>
import { ref, onMounted, onUnmounted, watch } from 'vue';
import lottie from 'lottie-web';
// 定义 Props
const props = defineProps({
// 动画 JSON 文件路径
animationData: {
type: Object,
required: false,
default: null
},
path: {
type: String,
required: false,
default: ''
},
// 动画宽高
width: {
type: String,
default: '300px'
},
height: {
type: String,
default: '300px'
},
// 是否自动播放
autoplay: {
type: Boolean,
default: true
},
// 是否循环播放
loop: {
type: Boolean,
default: true
},
// 动画速度（1 为正常速度）
speed: {
type: Number,
default: 1
},
// 渲染方式（svg/canvas/html），优先 svg（矢量）
renderer: {
type: String,
default: 'svg',
validator: (val) => ['svg', 'canvas', 'html'].includes(val)
}
});
// 定义 Emits：暴露动画状态事件
const emit = defineEmits(['complete', 'loopComplete', 'enterFrame']);
// 动画容器 Ref
const lottieContainer = ref(null);
// Lottie 实例
let lottieInstance = null;
// 初始化动画
const initLottie = () => {
if (!lottieContainer.value) return;
// 销毁旧实例（避免重复渲染）
if (lottieInstance) {
lottieInstance.destroy();
}
// 创建 Lottie 实例
lottieInstance = lottie.loadAnimation({
container: lottieContainer.value, // 动画容器
animationData: props.animationData, // 动画 JSON 数据（本地导入）
path: props.path, // 动画 JSON 文件路径（远程/ public 目录）
renderer: props.renderer, // 渲染方式
loop: props.loop, // 循环播放
autoplay: props.autoplay, // 自动播放
name: 'lottie-animation' // 动画名称（可选）
});
// 设置动画速度
lottieInstance.setSpeed(props.speed);
// 监听动画事件
lottieInstance.addEventListener('complete', () => {
emit('complete'); // 动画播放完成
});
lottieInstance.addEventListener('loopComplete', () => {
emit('loopComplete'); // 动画循环完成
});
lottieInstance.addEventListener('enterFrame', (e) => {
emit('enterFrame', e); // 动画每一帧
});
};
// 监听 Props 变化，重新初始化
watch(
[() => props.path, () => props.animationData, () => props.loop, () => props.speed],
() => {
initLottie();
},
{ immediate: true }
);
// 组件卸载时销毁实例
onUnmounted(() => {
if (lottieInstance) {
lottieInstance.destroy();
lottieInstance = null;
}
});
</script>
<style scoped>
.lottie-container {
display: inline-block;
overflow: hidden;
}
</style>
2. 基础使用示例
在页面组件中引入并使用封装好的 LottieAnimation 组件，支持两种加载方式：
方式 1：加载 public 目录下的 JSON 文件
将动画文件 animation.json 放入 public/lottie/ 目录，使用 path 传入路径：
<template>
<div class="demo-page">
<h2>Lottie 基础使用示例</h2>
<LottieAnimation
path="/lottie/animation.json"
width="200px"
height="200px"
:loop="false"
:speed="1.2"
@complete="handleAnimationComplete"
/>
</div>
</template>
<script setup>
import LottieAnimation from '@/components/LottieAnimation.vue';
// 动画播放完成回调
const handleAnimationComplete = () => {
console.log('动画播放完成！');
};
</script>
方式 2：本地导入 JSON 文件（需配置 loader）
如果将动画文件放在 src/assets 目录，需先导入 JSON 文件（Vue3 + Vite 无需额外配置，Webpack 需确保支持 JSON 导入）：
<template>
<div class="demo-page">
<LottieAnimation
:animation-data="animationData"
width="200px"
height="200px"
:autoplay="false"
ref="lottieRef"
/>
<button @click="playAnimation">播放动画</button>
<button @click="pauseAnimation">暂停动画</button>
</div>
</template>
<script setup>
import { ref } from 'vue';
import LottieAnimation from '@/components/LottieAnimation.vue';
// 导入本地 JSON 动画文件
import animationData from '@/assets/lottie/animation.json';
const animationData = ref(animationData);
const lottieRef = ref(null);
// 播放动画
const playAnimation = () => {
lottieRef.value.lottieInstance.play();
};
// 暂停动画
const pauseAnimation = () => {
lottieRef.value.lottieInstance.pause();
};
</script>
四、高级配置与交互控制
Lottie 提供了丰富的 API 用于控制动画，以下是常用的交互场景：
1. 手动控制播放 / 暂停 / 停止
通过获取 Lottie 实例，调用内置方法：
// 播放动画
lottieInstance.play();
// 暂停动画
lottieInstance.pause();
// 停止动画（重置到第一帧）
lottieInstance.stop();
// 跳转到指定帧（frameNum 为帧编号）
lottieInstance.goToAndStop(frameNum, true);
// 跳转到指定帧并播放
lottieInstance.goToAndPlay(frameNum, true);
2. 动态修改动画速度
javascript
运行
// 设置速度（0.5 为慢放，2 为快放）
lottieInstance.setSpeed(0.5);
// 获取当前速度
const currentSpeed = lottieInstance.playSpeed;
3. 控制循环模式
// 设置循环次数（0 为无限循环，1 为播放 1 次）
lottieInstance.loop = 0;
// 单独设置循环（立即生效）
lottieInstance.setLoop(true); // 无限循环
lottieInstance.setLoop(3); // 循环 3 次
4. 监听动画进度
通过 enterFrame 事件监听动画进度，实现进度条联动：
<template>
<LottieAnimation
path="/lottie/animation.json"
@enterFrame="handleEnterFrame"
/>
<input
type="range"
min="0"
max="100"
v-model="progress"
@input="handleProgressChange"
/>
</template>
<script setup>
import { ref } from 'vue';
const progress = ref(0);
let totalFrames = 0;
// 监听每一帧，更新进度
const handleEnterFrame = (e) => {
totalFrames = e.totalFrames;
progress.value = Math.floor((e.currentFrame / totalFrames) * 100);
};
// 拖动进度条，跳转动画
const handleProgressChange = () => {
const targetFrame = (progress.value / 100) * totalFrames;
lottieInstance.goToAndPlay(targetFrame, true);
};
</script>
五、性能优化与注意事项
1. 性能优化
-
懒加载：非首屏动画使用
v-if或动态导入，按需初始化； -
销毁实例：组件卸载时务必调用
destroy()销毁实例，避免内存泄漏； -
选择渲染方式：优先使用
svg渲染（矢量、轻量），复杂动画可使用canvas； - 压缩 JSON 文件：使用 LottieFiles 在线工具压缩动画 JSON，减少体积。
2. 常见问题解决
-
动画不显示：检查容器宽高是否设置、JSON 文件路径是否正确（
path以/开头表示 public 根目录）； - 动画卡顿：减少动画层数和复杂路径，避免同时播放多个大型动画；
- 跨域问题：远程加载 JSON 文件需确保服务端开启 CORS；
-
Vue3 打包路径问题：
animationData导入本地 JSON 时，Vite 需确保assetsInclude包含.json（默认已支持）。
六、总结
Lottie 是 Vue3 项目中实现高品质动画的最佳选择之一，通过封装通用组件可快速集成到项目中，结合其丰富的 API 能实现灵活的交互控制。本文从基础安装、组件封装、高级交互到性能优化，覆盖了 Lottie 在 Vue3 中的核心使用场景。合理使用 Lottie 可显著提升页面交互体验，同时兼顾性能与兼容性。
如果需要更复杂的场景（如动画分段播放、结合 Vuex/Pinia 控制动画状态），可基于本文的通用组件扩展，结合业务需求定制化开发。
