lottie

FrameVideo 的 Lottie

适用场景

以下情况适合使用 Lottie：

• After Effects 导出文件 — 设计师提供 .json 或 .lottie 文件
• Logo 动画 — 动态品牌标识和图标
• 预制动画 — 使用 LottieFiles 库中的素材
• 复杂的矢量动画 — 形状变形、路径动画
• 设计交接 — 设计师使用 AE 制作，开发者直接集成

不适用场景

以下情况请避免使用 Lottie：

• 代码驱动的动画 — 使用 gsap（更加灵活）
• 简单变换 — 使用 gsap 或 css-animations（更加轻量）
• 3D 场景 — 使用 three
• 大量文字的动画 — Lottie 对文字的处理效果不佳，请使用 HTML + GSAP
• 动态内容 — Lottie 动画是静态的，请使用程序化动画

---

快速入门

基础 lottie-web 动画：

<div id="logo-lottie" class="lottie-layer"></div>

<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
<script>
  const anim = lottie.loadAnimation({
    container: document.getElementById("logo-lottie"),
    renderer: "svg",
    loop: false,        // REQUIRED for FrameVideo
    autoplay: false,    // REQUIRED for FrameVideo
    path: "assets/logo-reveal.json",
  });

  window.__fvLottie = window.__fvLottie || [];
  window.__fvLottie.push(anim);
</script>

<style>
  .lottie-layer { width: 100%; height: 100%; }
</style>

要点：

1. 设置 autoplay: false 和 loop: false
2. 在 window.__fvLottie 数组中注册
3. 从本地 assets/ 加载，而不是使用远程 URL

---

约定

• 从本地项目文件加载素材，通常位于 assets/ 下。
• 设置 autoplay: false。
• 除非用户明确要求循环播放，否则优先设置 loop: false。
• 将每个返回的动画或播放器注册到 window.__fvLottie。
• 使用 CSS 保持 Lottie 容器尺寸稳定。

适配器通过 goToAndStop(timeMs, false) 控制 lottie-web 的播放进度；对于 dotLottie，则根据播放器形态使用帧或百分比 API。

lottie-web 用法

<div id="logo-lottie" class="lottie-layer"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
<script>
  const anim = lottie.loadAnimation({
    container: document.getElementById("logo-lottie"),
    renderer: "svg",
    loop: false,
    autoplay: false,
    path: "assets/logo-reveal.json",
  });

  window.__fvLottie = window.__fvLottie || [];
  window.__fvLottie.push(anim);
</script>

.lottie-layer {
  width: 100%;
  height: 100%;
}

dotLottie 用法

<canvas id="product-lottie" class="lottie-canvas"></canvas>
<script src="https://unpkg.com/@lottiefiles/dotlottie-web"></script>
<script>
  const player = new DotLottie({
    canvas: document.getElementById("product-lottie"),
    src: "assets/product-flow.lottie",
    autoplay: false,
    loop: false,
  });

  window.__fvLottie = window.__fvLottie || [];
  window.__fvLottie.push(player);
</script>

.lottie-canvas {
  width: 100%;
  height: 100%;
  display: block;
}

多个动画

将每个播放器都推入同一个注册表：

window.__fvLottie = window.__fvLottie || [];
window.__fvLottie.push(backgroundAnim);
window.__fvLottie.push(iconAnim);
window.__fvLottie.push(confettiAnim);

FrameVideo 会将它们全部定位到相同的合成时间。

适用场景

• 已知可通过 lottie-web 正确渲染的 After Effects 导出文件。
• Logo 显现动画、图标循环动画、装饰性点缀和产品 UI 动效。
• 将 Remotion Lottie 的用法转换为纯 FrameVideo HTML。

避免

• 在渲染时依赖远程 path URL。
• 使用 play() 开始播放。
• 假设 After Effects 中不受支持的效果导出后仍能正常呈现。请先在浏览器中测试 JSON 或 .lottie 文件。
• 异步加载播放器，并在 FrameVideo 验证完页面后才进行注册。

验证

编辑 Lottie 合成后：

npx framevideo lint
npx framevideo validate

致谢与参考资料

• FrameVideo 适配器源码：packages/core/src/runtime/adapters/lottie.ts。
• Airbnb 的 lottie-web：https://github.com/airbnb/lottie-web
• lottie-web loadAnimation 选项：https://github.com/airbnb/lottie-web/wiki/loadAnimation-options
• LottieFiles 的 dotLottie Web 播放器方法：https://developers.lottiefiles.com/docs/dotlottie-player/dotlottie-web/methods