Vue3 中 Lottie 动画库的使用指南

不想秃头的程序员2025-12-31 10:34

Lottie 是 Airbnb 开源的一款跨平台动画渲染库，能够将 AE（After Effects）制作的动画导出为 JSON 格式，并在 Web、iOS、Android 等平台无缝渲染，完美还原设计师的动画效果。在 Vue3 项目中集成 Lottie，既能提升页面交互体验，又能避免传统 GIF / 视频动画的性能问题和体积冗余。本文将详细讲解 Vue3 中 Lottie 的安装、基础使用、高级配置及实战技巧。

一、核心优势

在开始集成前，先了解 Lottie 适配 Vue3 项目的核心价值：

  1. 轻量化：JSON 动画文件体积远小于 GIF / 视频，且支持按需加载；
  2. 可交互：可通过代码控制动画播放、暂停、跳转、循环等，支持自定义交互逻辑；
  3. 矢量渲染：动画基于矢量，适配不同分辨率设备无模糊；
  4. Vue3 友好：支持组合式 API（Setup），可封装为通用组件，复用性强。

二、环境准备与安装

1. 依赖安装

Vue3 项目中推荐使用 lottie-web（官方 Web 端实现），通过 npm/yarn/pnpm 安装：

shell 复制代码 
# 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：

js 复制代码 
<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 传入路径：

js 复制代码 
<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 导入）：

js 复制代码 
<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 实例，调用内置方法：

js 复制代码 
// 播放动画
lottieInstance.play();

// 暂停动画
lottieInstance.pause();

// 停止动画（重置到第一帧）
lottieInstance.stop();

// 跳转到指定帧（frameNum 为帧编号）
lottieInstance.goToAndStop(frameNum, true);

// 跳转到指定帧并播放
lottieInstance.goToAndPlay(frameNum, true);

2. 动态修改动画速度

javascript

运行

ini 复制代码 
// 设置速度（0.5 为慢放，2 为快放）
lottieInstance.setSpeed(0.5);

// 获取当前速度
const currentSpeed = lottieInstance.playSpeed;

3. 控制循环模式

js 复制代码 
// 设置循环次数（0 为无限循环，1 为播放 1 次）
lottieInstance.loop = 0;

// 单独设置循环（立即生效）
lottieInstance.setLoop(true); // 无限循环
lottieInstance.setLoop(3); // 循环 3 次

4. 监听动画进度

通过 enterFrame 事件监听动画进度，实现进度条联动：

js 复制代码 
<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 控制动画状态），可基于本文的通用组件扩展，结合业务需求定制化开发。

相关推荐
崔庆才丨静觅5 小时前
hCaptcha 验证码图像识别 API 对接教程
前端
passerby60616 小时前
完成前端时间处理的另一块版图
前端·github·web components
掘了6 小时前
「2025 年终总结」在所有失去的人中，我最怀念我自己
前端·后端·年终总结
崔庆才丨静觅6 小时前
实用免费的 Short URL 短链接 API 对接说明
前端
崔庆才丨静觅6 小时前
5分钟快速搭建 AI 平台并用它赚钱！
前端
崔庆才丨静觅7 小时前
比官方便宜一半以上！Midjourney API 申请及使用
前端
Moment7 小时前
富文本编辑器在 AI 时代为什么这么受欢迎
前端·javascript·后端
崔庆才丨静觅7 小时前
刷屏全网的“nano-banana”API接入指南！0.1元/张量产高清创意图，开发者必藏
前端
剪刀石头布啊7 小时前
jwt介绍
前端
爱敲代码的小鱼7 小时前
AJAX（异步交互的技术来实现从服务端中获取数据）：
前端·javascript·ajax
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03openclaw配置教程（linux+局域网ollama）04UV安装并设置国内源05OpenClaw Chrome扩展使用教程 - 浏览器中继控制06Linux下V2Ray安装配置指南07Claude Code Skills 实用使用手册08Vue-skills的中文文档09让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南10一文了解国产算子编程语言 TileLang，TileLang 对国产开源生态的影响与启示