如何在 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-web
import 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 不重新挂载:改 animationData prop 不会重新加载动画。如果数据变了, 要么在以数据为依赖的 effect 里销毁并重建动画, 要么给组件一个 key prop,让 React 挂载一个全新的实例。

该选哪种方案?

想把动画丢进页面就完事,用 lottie-react:代码更少, 挂载和清理都帮你处理了,lottieRef 这个逃生口也能覆盖大多数控制需求。 需要事件监听(animation.addEventListener("complete", ...))、 分段播放、多个动画共用一个播放器实例,或封装没暴露的其他能力时, 直接用 lottie-web。无论选哪种,记住三条规则: 给容器定尺寸、卸载时 destroy、播放器只放客户端。 如果动画文件本身很重,先看Lottie、GIF 与 MP4 的对比, 再考虑文件是不是该换成 .lottie 包, 见dotLottie 与 JSON 的对比。