如何在 React 中嵌入 Lottie
Lottie 动画只是 JSON 文件,所以在 React 里渲染它,本质上就是把这份 JSON 交给播放器, 再给播放器一个 DOM 节点去绘制。主流做法有两种:底层的 lottie-web 库, 提供完整的播放控制;以及 lottie-react 封装,帮你省掉样板代码。 本文两种都讲,再加上容易踩坑的清理、SSR 与 TypeScript 细节。
方案一:直接用 lottie-web
lottie-web 是官方参考播放器。调用 lottie.loadAnimation(),传入容器元素和动画数据, 它会返回一个可控制的动画实例。先安装:
npm install lottie-web然后在 useEffect 里用 ref 挂接容器:
import { useEffect, useRef } from "react";
import lottie from "lottie-web";
import animationData from "./checkmark.json";
export default function Checkmark() {
const containerRef = useRef<HTMLDivElement>(null);
useEffect(() => {
if (!containerRef.current) return;
const animation = lottie.loadAnimation({
container: containerRef.current,
renderer: "svg",
loop: true,
autoplay: true,
animationData,
});
return () => animation.destroy();
}, []);
return <div ref={containerRef} style={{ width: 120, height: 120 }} />;
}几点注意。renderer 通常用 "svg":最清晰, 也是大多数场景的默认选择。"canvas" 适合形状极多、 对性能敏感的场景,"html" 是很少用到的旧版兜底。 容器 div 必须有明确尺寸——SVG 会填满你给的尺寸, 不设宽高它会缩成零。
控制播放
loadAnimation 返回的动画实例就是你的遥控器。 把它存进 ref,事件处理函数就能拿到:
const animationRef = useRef<ReturnType<typeof lottie.loadAnimation> | null>(null);
// 在 useEffect 里,loadAnimation 之后:
animationRef.current = animation;
// 在组件的任何地方:
animationRef.current?.play();
animationRef.current?.pause();
animationRef.current?.setSpeed(1.5);
animationRef.current?.goToAndPlay(30, true); // 跳到第 30 帧并播放
animationRef.current?.goToAndStop(0, true); // 跳到第 0 帧并停住goToAndPlay 和 goToAndStop 的第二个参数是 isFrame:传 true 按帧号定位,传 false 按秒定位。常见用法包括点击按钮播放一次性成功动画、 请求完成时暂停加载器,以及用 goToAndStop(progress * totalFrames, true) 把进度绑定到滚动位置。
清理:卸载时 destroy
这是最常被遗忘的一步,也是 bug 最多的地方。Lottie 动画会保持一个 requestAnimationFrame 循环运行,并持有 DOM 节点的引用。 如果组件卸载时没有清理,循环会继续对着已 detached 的节点跑, 泄漏内存,在 Strict Mode 或快速跳转时还会在重新挂载后叠加重复动画。 一定要在 effect 里返回清理函数:
useEffect(() => {
const animation = lottie.loadAnimation({ /* ... */ });
return () => animation.destroy();
}, []);destroy() 会停止帧循环、移除事件监听并清空容器。 如果你把实例存在 ref 里,在同一个清理函数里把它置为 null,防止处理函数调用已销毁实例的方法。
方案二:lottie-react
如果不需要精细控制,lottie-react 把 lottie-web 包成一个 React 组件,替你处理生命周期。 和播放器一起安装:
npm install lottie-react lottie-webimport Lottie from "lottie-react";
import animationData from "./checkmark.json";
export default function Checkmark() {
return <Lottie animationData={animationData} loop autoplay style={{ width: 120, height: 120 }} />;
}整个组件就是这样。需要控制播放时,通过 lottieRef prop 传一个 ref——注意是 lottieRef,不是常规的 ref—— 你会拿到同一个动画实例:
import { useRef } from "react";
import Lottie, { type LottieRefCurrentProps } from "lottie-react";
import animationData from "./checkmark.json";
export default function Checkmark() {
const lottieRef = useRef<LottieRefCurrentProps>(null);
return (
<>
<Lottie lottieRef={lottieRef} animationData={animationData} loop={false} autoplay={false} />
<button onClick={() => lottieRef.current?.play()}>Play</button>
<button onClick={() => lottieRef.current?.pause()}>Pause</button>
<button onClick={() => lottieRef.current?.setSpeed(2)}>2x speed</button>
</>
);
}通过 lottieRef 暴露的实例支持和原生播放器一样的方法——play()、pause()、setSpeed()、 goToAndPlay()、goToAndStop() 和 destroy()—— 所以可以先简单起步,以后需要更多控制时也不用换库。
SSR:动态导入与 "use client"
Lottie 需要 DOM,所以无法在服务端渲染期间运行。在 Next.js App Router 项目里, 有两件事必须做对。
第一,任何碰到 lottie-web 的组件都必须是客户端组件: 在文件顶部写 "use client"。没有它,服务端会尝试执行播放器代码, 在缺失浏览器全局对象时报错。
第二,如果想更稳妥——或者动画数据很大—— 用 next/dynamic 配合 ssr: false 懒加载播放器:
import dynamic from "next/dynamic";
const Checkmark = dynamic(() => import("./Checkmark"), { ssr: false });
export default function Page() {
return <Checkmark />;
}这样播放器完全不会进入服务端包,也不会进入初始客户端包, 页面先加载,动画代码随后到达。动画数据本身也可以运行时 fetch 而不是静态导入,这样它就不会进 JS 包—— 对大文件值得这么做,尤其是有内嵌位图帧的文件。 如果你的文件正是这种,先读为什么你的 Lottie 文件有 70 MB, 再用lottie-mini 压缩工具跑一遍。
TypeScript 要点
- 导入 JSON:在
tsconfig.json里开启resolveJsonModule: true(Next.js 默认开启)后,import animationData from "./checkmark.json"会自动获得类型。 没开启的话,需要声明文件,或者改用fetch+JSON.parse。 - 实例类型:
lottie.loadAnimation()的返回类型是AnimationItem,从lottie-web导出。 给 ref 用这个类型,不要用any。 - lottie-react 类型:封装自带类型,包括 ref 用的
LottieRefCurrentProps和组件 props 用的LottieComponentProps。 - 动画数据结构:如果你要自己给 JSON 写类型,顶层是包含
v、fr、ip、op、w、h、layers和assets的对象。实际中直接导入 JSON 让 TypeScript 推断类型更简单, 也不容易出错。
监听事件
有时你需要在动画结束时做点什么——比如隐藏成功对勾、显示下一个界面。 动画实例会发出事件,用 addEventListener 订阅:
useEffect(() => {
const animation = lottie.loadAnimation({ /* ... */ });
const onComplete = () => {
console.log("Animation finished");
};
animation.addEventListener("complete", onComplete);
return () => {
animation.removeEventListener("complete", onComplete);
animation.destroy();
};
}, []);complete 事件在不循环的动画播到最后一帧时触发。loopComplete 在每轮循环结束时触发,enterFrame 在每帧触发并带上当前帧号—— 方便把别的东西和动画进度同步。 在调用 destroy() 的同一个清理函数里移除监听, 这样重新挂载时不会叠加重复的处理函数。
播放片段
一个动画文件可以装多个状态——比如 0–30 帧是待机循环,30–60 帧是成功爆发。 不用导出两个文件,用 playSegments 只播需要的片段:
// 只播 30 到 60 帧,然后停住:
animation.playSegments([[30, 60]], true);
// 只播第一个片段(开启 loop 时会重复):
animation.playSegments([[0, 30]], true);第一个参数是 [startFrame, endFrame] 对的数组, 第二个参数 forceFlag 告诉播放器立即跳到该片段, 而不是播完当前帧再说。大多数按钮和状态切换动画就是这么做的: 一个文件、几个片段,组件里一个小状态机决定播哪一段。
运行时加载动画数据
静态导入 JSON 会把它打进 JavaScript 包,对小图标没问题, 对大动画就是浪费。几百 KB 以上的文件,改成运行时 fetch:
useEffect(() => {
let animation: ReturnType<typeof lottie.loadAnimation> | null = null;
fetch("/animations/hero.json")
.then((res) => res.json())
.then((animationData) => {
if (!containerRef.current) return;
animation = lottie.loadAnimation({
container: containerRef.current,
renderer: "svg",
loop: true,
autoplay: true,
animationData,
});
});
return () => animation?.destroy();
}, []);这样动画完全不进 JS 包,页面在动画数据到达之前就可交互了。 还可以把文件放到 CDN 上,或不重新部署应用就换掉它。 同样的模式适用于 lottie-react:先 fetch JSON 存进 state, 数据加载完成后再渲染 <Lottie>。
常见坑
- Strict Mode 双挂载:开发环境下,React 18+ 会把 effect 挂载两次。 如果 effect 创建动画时没有清理函数,一个容器里会出现两个动画。
destroy()清理能解决这个问题——这也是永远不要跳过它的又一个理由。 - 忘了给容器尺寸:空的
div高度为零, 动画就渲染进了一片虚无。一定要给容器明确尺寸,或用 CSS 宽高比。 - autoplay 配 loop: false:一次性动画播一遍就停在最后一帧。 对成功状态这通常正是想要的,但如果组件在用户看到之前就挂载了, 动画可能已经播完了。设
autoplay: false,在合适的时刻调用play()。 - 换 animationData 不重新挂载:改
animationDataprop 不会重新加载动画。如果数据变了, 要么在以数据为依赖的 effect 里销毁并重建动画, 要么给组件一个keyprop,让 React 挂载一个全新的实例。
该选哪种方案?
想把动画丢进页面就完事,用 lottie-react:代码更少, 挂载和清理都帮你处理了,lottieRef 这个逃生口也能覆盖大多数控制需求。 需要事件监听(animation.addEventListener("complete", ...))、 分段播放、多个动画共用一个播放器实例,或封装没暴露的其他能力时, 直接用 lottie-web。无论选哪种,记住三条规则: 给容器定尺寸、卸载时 destroy、播放器只放客户端。 如果动画文件本身很重,先看Lottie、GIF 与 MP4 的对比, 再考虑文件是不是该换成 .lottie 包, 见dotLottie 与 JSON 的对比。