lottie-animation

Lottie アニメーション

After Effects からプロダクトへ橋渡しする、JSON（または圧縮された .lottie）形式で配信されるベクターアニメーションです。軽量で解像度に依存せず、Web、iOS、Android、React Native 上でランタイムにより再生できます。このスキルでは、Lottie の統合、制御、書き出しを扱います。

使用する場面

• デザイナーが作成した AE アニメーションを Web／iOS／Android／React Native に配信する
• ループするイラスト、オンボーディング、空の状態、アニメーションアイコン
• スクロールや操作（ホバー、クリック、カーソル）に連動したベクターアニメーションの再生
• ブランドごとに再書き出しする代わりに、ランタイムでテーマ設定や色の変更を行う

形式：.json と .lottie

• .json — Bodymovin の生の出力です。人が読みやすい一方、サイズは大きくなります。
• .lottie — 圧縮されたコンテナ形式です（多くの場合、60～80％小さくなります）。複数のアニメーション、画像、テーマをまとめられます。配信にはこちらを推奨します。プレイヤーには @lottiefiles/dotlottie-web（モダンな Canvas＋WASM 対応）を使用します。旧式の lottie-web の後継です。

新規開発では dotLottie ランタイムを優先してください。従来の .json や SVG レンダラーが必要な場合にのみ lottie-web を使用します。

基本的なワークフロー（Web、dotLottie）

npm i @lottiefiles/dotlottie-web        # vanilla
npm i @lottiefiles/dotlottie-react      # React wrapper

Vanilla：

import { DotLottie } from "@lottiefiles/dotlottie-web";

const dotLottie = new DotLottie({
  canvas: document.querySelector("#lottie"),  // a <canvas> element
  src: "/hero.lottie",                         // or .json
  loop: true,
  autoplay: true,
  // speed: 1, mode: "forward" | "reverse" | "bounce", renderConfig: { autoResize: true }
});

React：

import { DotLottieReact } from "@lottiefiles/dotlottie-react";

function Hero() {
  return <DotLottieReact src="/hero.lottie" loop autoplay style={{ width: 320 }} />;
}

インスタンスを取得して制御します。

const [dl, setDl] = useState(null);
<DotLottieReact src="/icon.lottie" dotLottieRefCallback={setDl} />;
// dl?.play(); dl?.pause(); dl?.setSpeed(2);

再生の制御

dotLottie.play();
dotLottie.pause();
dotLottie.stop();
dotLottie.setSpeed(1.5);
dotLottie.setMode("bounce");        // forward | reverse | bounce | reverse-bounce
dotLottie.setFrame(42);             // jump to a frame
dotLottie.setSegment(30, 90);       // constrain playback to a frame range (e.g. a "loading" loop)

イベントを使ってシーケンスや UI を制御します。

dotLottie.addEventListener("load", () => { /* totalFrames now available */ });
dotLottie.addEventListener("complete", () => { /* non-looping playback finished */ });
dotLottie.addEventListener("frame", ({ currentFrame }) => { /* per-frame */ });

ステートマシン形式（例：「チェック済み」区間を再生した後に待機するボタン）：区間を再生し、complete をリッスンしてから、setSegment で待機ループに切り替えます。

スクロール連動の Lottie（GSAP 不要）

スクロールの進行度（0～1）をフレームに割り当てます。自動再生を一時停止し、フレームを手動で制御します。

const dotLottie = new DotLottie({ canvas, src: "/scroll.lottie", autoplay: false });
let total = 0;
dotLottie.addEventListener("load", () => { total = dotLottie.totalFrames; });

window.addEventListener("scroll", () => {
  const el = canvas.closest(".scrolly");
  const rect = el.getBoundingClientRect();
  const p = clamp(-rect.top / (rect.height - window.innerHeight), 0, 1); // 0..1 through the section
  dotLottie.setFrame(p * (total - 1));
}, { passive: true });

const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));

より複雑な操作（ホバーで再生、クリックで切り替え、カーソル追従）を、配線コードを書かずに実装するには、@lottiefiles/lottie-interactivity を使用します。scroll、hover、click、play、cursor モードを、宣言的にフレーム範囲へ割り当てられます。

ランタイムでのテーマ設定／色の変更

方法は 2 つあります。

• dotLottie のテーマ：.lottie に名前付きのカラーテーマを埋め込み、dotLottie.setTheme("dark")／loadTheme(...) で切り替えられます。LottieFiles のツールで作成でき、色を変更するための再書き出しは不要です。
• 手動で色を上書き：JSON を読み込み、layers[].shapes[] を走査して c.k のカラー配列（正規化された 0～1 の RGBA）を書き換えてから、変更後のオブジェクトでプレイヤーを初期化します。レイヤー構造に依存するため壊れやすくなります。テーマを使うか、クラス単位でスタイルを変更する必要がある場合は CSS 駆動の SVG レンダラー（lottie-web の rendererSettings）を優先してください。

モバイルランタイム（機能対応）

• iOS — lottie-ios（LottieAnimationView）：.play()、.currentProgress、.play(fromFrame:toFrame:)。
• Android — lottie-android（LottieAnimationView／Compose の LottieAnimation）：setMinAndMaxFrame、progress。
• React Native — lottie-react-native（<LottieView source={...} progress={anim} />。Animated で progress を制御します）。

同じ .lottie／.json をすべての環境で再生できます。区間と進行度の考え方は Web API と共通です。

最適化

• 生の .json よりも圧縮された .lottie を配信します。画面外のプレイヤーは遅延読み込みし、表示されていない間は一時停止します（IntersectionObserver → play／pause）。
• 同時に多数のアニメーションを再生する場合は、Canvas／WASM の dotLottie レンダラーを優先します。SVG レンダラー（lottie-web）は、鮮明なアイコン 1 つには適していますが、複雑なファイルでは DOM の負荷が高くなります。
• AE コンポジションは小さく保ちます。レイヤーやキーフレームを減らし、大きな埋め込みラスター画像を避け、可能であればプリコンポジションを統合します。ファイルサイズは再生時間ではなく、キーフレームとパスの複雑さに左右されます。
• ブランドやテーマごとにファイルを書き出す代わりに、ランタイムで色を変更します（テーマを使用）。

提供と検証（スタンドアロン HTML）

同梱ヘルパー（scripts/）：scripts/seek-shot.sh anim.html 0 1.5 3 は ?t=N ハーネスで各時点のフレームを固定してスクリーンショットを撮影します。scripts/contact-sheet.sh sheet.png frame-*.png はそれらをタイル状に並べ、一目で確認できる一覧を作成します。詳しくは scripts/README.md をご覧ください。

自己完結型の Lottie デモ（ループするイラスト、アニメーションアイコン、空の状態）では、納品物はブラウザーで直接開ける 1 つの HTML ファイルです。CDN の dotLottie／lottie-web ランタイム、<canvas>、そして .lottie／.json（相対ファイルまたはデータ URL）を含みます。ビルド手順は不要です。プレーヤーの提供には 1 ファイルが適切な構成です。バンドラーは使わないでください。

出力要件：

• .html ファイル 1 つ：CDN 経由のランタイム（@lottiefiles/dotlottie-web）、キャンバス、およびフレームを手動で制御できる autoplay:false。
• 任意のフレームをスクリーンショット用に固定できるシークハーネスを含めてください。

シークハーネス — 特定のフレームを固定します。 ?t=N はフレームに移動してその位置で停止するため、スクリーンショットに決定的な静止フレームが収まります。Lottie の再生位置はフレーム単位なので、フレームを直接指定して停止します。

<script>
  const dl = new DotLottie({ canvas, src: "/icon.lottie", autoplay: false });
  dl.addEventListener("load", () => {
    const t = new URLSearchParams(location.search).get("t");
    if (t !== null) dl.setFrame(parseFloat(t));      // freeze on frame N (lottie-web: anim.goToAndStop(N, true))
    else dl.play();
    console.log("totalFrames", dl.totalFrames);       // read for end-frame
    window.__ready = true;
  });
</script>

ループの検証 — 描画 → 固定 → スクリーンショット → 確認： ファイルを最初／中間／最後のフレーム（?t=0、?t=<total/2>、?t=<total-1>）で開きます（コンソールで totalFrames を確認してください）。それぞれスクリーンショットを撮影し、忠実度（色／テーマが正しいか、意図した箇所でセグメントがループするか）とアーティファクト（autoResize／DPR の設定漏れによるキャンバスのぼやけ、コンポジションの切れ、ファイルの読み込み前に発生する FOUC、カクつき）を確認します。ヘッドレスツールならどれでも使えます。

npx playwright screenshot --wait-for-timeout=600 "file://$PWD/lottie.html?t=42" frame-mid.png

完了前の確認事項：

1. スタンドアロンで開けること — コンソールエラーがなく、CDN ランタイムと .lottie／.json が読み込まれること。
2. ?t=N（setFrame／goToAndStop）で正確かつ決定的なフレームに固定できること。
3. 最初／中間／最後のフレームでスクリーンショットを撮影し、要件に合致し、鮮明で、切れていないことを確認すること。
4. prefers-reduced-motion に対応すること — ループを autoplay せず、静止フレームを表示するか、再生コントロールを用意してください。
5. イージングに意図があること — 再生速度／セグメントを目的に応じて選び、AE で作成したモーションが意図どおりに見えるようにしてください。

クイックリファレンス

目的	呼び出し
範囲を再生	setSegment(start, end)
フレームに移動	setFrame(n)
逆再生／往復再生	`setMode("reverse"
スクロール連動	autoplay:false + setFrame(p*totalFrames)
テーマの切り替え	setTheme("dark")
長さの確認	load イベント後の totalFrames
宣言的なインタラクティブ機能	@lottiefiles/lottie-interactivity

リファレンスファイル

• references/integration-and-export.md — dotLottie-web と React の完全なセットアップ、イベント／セグメント制御、lottie-interactivity のモード設定、スクロール／カーソルのパターン、ランタイムのテーマ設定の詳細、およびサポートされていない AE 機能の一覧と回避方法を含む、After Effects → Bodymovin の完全なエクスポートチェックリスト。