Загрузка из JSON-объекта

Lottie Web поддерживает несколько способов инициализации анимаций, и один из наиболее гибких вариантов — загрузка напрямую из JSON-объекта. Этот подход используется, когда данные анимации уже доступны в памяти приложения, были получены через API, импортированы как модуль или сформированы динамически.

JSON-объект Lottie представляет собой структурированное описание анимации: композиции, слои, ключевые кадры, эффекты и интерполяции. В отличие от загрузки через URL, при работе с объектом отсутствует этап сетевого запроса, что делает метод предпочтительным в SPA, PWA и сервер-сайд рендеринге с последующей гидратацией.

Базовый механизм загрузки через animationData

Основной способ передачи JSON-объекта — свойство animationData при инициализации анимации.

import lottie from "lottie-web";

import animationJson from "./animation.json";

const animation = lottie.loadAnimation({
  container: document.getElementById("lottie"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  animationData: animationJson
});

В этом примере JSON импортируется как модуль (при использовании сборщиков вроде Webpack, Vite или Rollup), после чего передаётся напрямую в движок Lottie.

Ключевые параметры:

  • container — DOM-элемент, в котором будет рендериться анимация
  • renderer — тип рендеринга (svg, canvas, html)
  • loop — зацикливание анимации
  • autoplay — автоматический запуск
  • animationData — сам JSON-объект анимации

При наличии animationData параметр path игнорируется.

Загрузка JSON через fetch и последующая передача

Часто JSON хранится на сервере или в статических ресурсах. В этом случае используется асинхронная загрузка.

import lottie from "lottie-web";

const container = document.getElementById("lottie");

fetch("/animations/data.json")
  .then(response => response.json())
  .then(data => {
    lottie.loadAnimation({
      container,
      renderer: "svg",
      loop: true,
      autoplay: true,
      animationData: data
    });
  });

Этот подход позволяет централизованно управлять анимациями без пересборки приложения. Особенно полезен в системах с динамической загрузкой контента.

Использование JSON, полученного из API

При интеграции с backend JSON часто приходит как часть ответа API.

import lottie from "lottie-web";

async function initAnimation() {
  const response = await fetch("/api/animation");
  const animationData = await response.json();

  lottie.loadAnimation({
    container: document.getElementById("lottie"),
    renderer: "svg",
    loop: true,
    autoplay: true,
    animationData
  });
}

initAnimation();

При таком подходе важно учитывать:

  • JSON должен полностью соответствовать формату Lottie
  • Недопустимы обрезанные или частично сериализованные данные
  • Желательно валидировать структуру перед передачей в loadAnimation

Импорт JSON как модуля

Современные сборщики позволяют импортировать JSON напрямую:

import animationData from "./animation.json";
import lottie from "lottie-web";

lottie.loadAnimation({
  container: document.querySelector("#lottie"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  animationData
});

В этом случае JSON становится частью бандла. Это уменьшает количество HTTP-запросов и ускоряет первичную загрузку интерфейса.

Динамическое создание JSON-объекта

Lottie допускает работу не только с готовыми файлами, но и с динамически сформированными структурами.

import lottie from "lottie-web";

const dynamicAnimation = {
  v: "5.7.4",
  fr: 30,
  ip: 0,
  op: 60,
  w: 200,
  h: 200,
  layers: [
    {
      ty: 4,
      nm: "Shape Layer",
      ks: {
        o: { a: 0, k: 100 },
        r: { a: 0, k: 0 },
        p: { a: 0, k: [100, 100, 0] },
        a: { a: 0, k: [0, 0, 0] },
        s: { a: 0, k: [100, 100, 100] }
      },
      shapes: [
        {
          ty: "el",
          p: { a: 0, k: [0, 0] },
          s: { a: 0, k: [80, 80] }
        }
      ]
    }
  ]
};

lottie.loadAnimation({
  container: document.getElementById("lottie"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  animationData: dynamicAnimation
});

Подобный подход применяется в системах генерации интерфейсов, визуализации данных и кастомных графических редакторах.

Важные особенности структуры JSON

Lottie JSON имеет строго определённую схему. При передаче объекта напрямую критично соблюдение следующих аспектов:

Версионность

Поле v определяет версию формата:

"v": "5.7.4"

Несовместимость версий может приводить к некорректному рендерингу слоёв или эффектов.

Кадровая сетка

Поля:

  • fr — frame rate
  • ip — стартовый кадр
  • op — конечный кадр

определяют временную шкалу анимации.

Слои

Массив layers является ядром композиции. Каждый слой может содержать:

  • трансформации (ks)
  • формы (shapes)
  • маски
  • вложенные композиции

Ошибка в структуре слоёв приводит к частичной или полной потере рендеринга.

Повторное использование JSON-объекта

Переданный animationData не клонируется глубоко внутри Lottie. Это означает, что изменение исходного объекта после инициализации может повлиять на поведение анимации.

const anim = lottie.loadAnimation({
  container,
  renderer: "svg",
  animationData: data
});

data.op = 30; // потенциально влияет на уже созданную анимацию

Для безопасной работы используется иммутабельность:

const safeData = structuredClone(data);

lottie.loadAnimation({
  container,
  renderer: "svg",
  animationData: safeData
});

Частые ошибки при загрузке JSON

Несоответствие формата

Если JSON не соответствует спецификации Lottie, анимация не будет отрисована без явной ошибки.

Потеря ключевых полей

Отсутствие layers, assets или fr приводит к пустому результату.

Неправильная сериализация

При передаче через API JSON может приходить в виде строки:

const data = JSON.parse(response.data);

Передача строки напрямую в animationData приводит к сбою.

Кросс-доменные ограничения

При загрузке через fetch могут возникать ограничения CORS, но при использовании animationData этот фактор отсутствует полностью.

Производственные сценарии использования

Клиентские приложения

JSON импортируется как модуль и входит в сборку, обеспечивая мгновенный доступ к анимации без задержек сети.

CMS-системы

Анимации хранятся как JSON в базе данных и загружаются динамически при рендере страницы.

Микрофронтенды

Каждый модуль может поставлять собственные Lottie-анимации как JSON-конфигурации, не завися от централизованных ассетов.

Интерактивные интерфейсы

JSON формируется на основе пользовательских действий и используется как реактивное описание визуальных эффектов.

Управление жизненным циклом после загрузки

После создания анимации через loadAnimation объект можно контролировать:

const anim = lottie.loadAnimation({
  container,
  renderer: "svg",
  animationData
});

anim.pause();
anim.play();
anim.stop();
anim.goToAndPlay(10, true);
anim.destroy();

При загрузке из JSON-объекта поведение этих методов идентично другим способам инициализации, однако важно учитывать, что сам JSON остаётся внешней сущностью и не связан с жизненным циклом экземпляра.

Оглавление