Обработка ошибок загрузки

Этапы загрузки анимации и точки возникновения сбоев

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

Ключевые этапы:

  • загрузка JSON (HTTP-запрос или локальный объект)
  • парсинг данных
  • валидация структуры анимации
  • инициализация рендерера (SVG / Canvas / HTML)
  • запуск анимационного цикла

Каждый этап генерирует собственный класс ошибок, которые не всегда выражаются через исключения JavaScript.

Ошибки сетевой загрузки JSON

Отсутствие ресурса (404 / 410)

Наиболее частая проблема — неверный путь к JSON-файлу анимации. В этом случае запрос завершается неуспешным HTTP-статусом, а библиотека не получает валидные данные.

Типичные причины:

  • ошибка в относительном пути
  • отсутствие файла на CDN
  • неверная конфигурация сборщика
  • динамически сформированный URL

Lottie Web не всегда бросает исключение в момент запроса. Вместо этого происходит переход в состояние неуспешной загрузки, фиксируемое через события.

CORS-ограничения

При загрузке JSON с другого домена возникает блокировка браузера:

  • отсутствуют заголовки Access-Control-Allow-Origin
  • запрос выполняется в режиме cross-origin без разрешения

Симптоматика:

  • отсутствие данных
  • сообщение о невозможности доступа к ресурсу в консоли браузера
  • срабатывание сетевой ошибки без детального описания внутри Lottie

Таймауты и нестабильная сеть

При медленном соединении возможны:

  • неполная загрузка JSON
  • прерывание запроса
  • зависание инициализации без перехода в состояние ready

Lottie Web не управляет тайм-аутами напрямую, поэтому контроль выполняется на уровне fetch или XMLHttpRequest.

Ошибки парсинга JSON

После получения данных выполняется JSON.parse. На этом этапе возникают критические сбои:

  • синтаксически некорректный JSON
  • повреждённый файл (обрезанный при загрузке)
  • наличие BOM или неожиданных символов
  • двойное экранирование при генерации на сервере

Такие ошибки приводят к невозможности построения внутренней модели анимации.

Характерные проявления:

  • отсутствие события data_ready
  • срабатывание data_failed
  • остановка инициализации без рендеринга

Ошибки структуры Lottie-анимации

Даже корректный JSON может не соответствовать спецификации Bodymovin.

Типичные проблемы:

  • отсутствует ключ layers
  • некорректные assets
  • повреждённые keyframes
  • несоответствие типов в свойствах анимации
  • ссылки на отсутствующие изображения или шрифты

Такие ошибки не всегда детектируются как исключения, но приводят к частичной или полной неработоспособности анимации.

Ошибки рендерера

SVG-рендерер

При использовании SVG возможны сбои:

  • некорректные path-данные
  • слишком сложные маски и матчи
  • превышение лимитов DOM-узлов
  • проблемы с clipPath и mask

Canvas-рендерер

Canvas-режим чувствителен к:

  • переполнению памяти при больших композициях
  • высокой частоте кадров при сложных сценах
  • ошибкам преобразования координат

HTML-рендерер

Редкий режим, но возможны:

  • ошибки вставки DOM-элементов
  • конфликты стилей CSS
  • некорректные трансформации

Событийная модель Lottie Web для отслеживания ошибок

Lottie Web использует событийную систему, которая позволяет отслеживать состояние загрузки.

Основные события

  • data_ready — данные успешно загружены и распарсены
  • data_failed — ошибка получения или обработки данных
  • DOMLoaded — завершено построение DOM/структуры
  • complete — завершение анимации

Ключевым для диагностики является событие:

  • data_failed — основной индикатор проблем загрузки

Пример обработки событий

const animation = lottie.loadAnimation({
  container: document.getElementById('anim'),
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: '/animations/example.json'
});

animation.addEventListener('data_failed', () => {
  console.error('Ошибка загрузки Lottie-анимации');
});

animation.addEventListener('DOMLoaded', () => {
  console.log('Анимация успешно инициализирована');
});

Обёртка для устойчивой загрузки

Для промышленных сценариев используется слой абстракции поверх Lottie Web, который добавляет:

  • контроль ошибок сети
  • повторные попытки загрузки
  • fallback-анимации
  • централизованное логирование

Пример устойчивого загрузчика

function loadLottieWithFallback(options, fallbackPath, retries = 2) {
  let attempt = 0;

  function init(path) {
    const anim = lottie.loadAnimation({
      ...options,
      path
    });

    anim.addEventListener('data_failed', () => {
      if (attempt < retries) {
        attempt++;
        init(path);
      } else if (path !== fallbackPath) {
        init(fallbackPath);
      }
    });

    return anim;
  }

  return init(options.path);
}

Повторные попытки загрузки (retry strategy)

Сетевые сбои часто носят временный характер. Для уменьшения вероятности отказа применяются стратегии:

  • фиксированное количество повторов
  • экспоненциальная задержка между попытками
  • переключение на резервный CDN
  • локальный кэш JSON

Пример экспоненциальной задержки:

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function fetchWithRetry(url, retries = 3) {
  let lastError;

  for (let i = 0; i < retries; i++) {
    try {
      const res = await fetch(url);
      if (!res.ok) throw new Error(res.status);
      return await res.json();
    } catch (e) {
      lastError = e;
      await delay(2 ** i * 300);
    }
  }

  throw lastError;
}

Использование локального JSON как fallback

Одним из устойчивых решений является отказ от сетевой загрузки в критических интерфейсах:

  • импорт JSON через сборщик
  • встроенные анимации в bundle
  • хранение в localStorage или IndexedDB
import animationData from './animation.json';

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

Логирование и диагностика

Для анализа ошибок используются следующие параметры:

  • URL анимации
  • renderer (svg/canvas/html)
  • размер JSON
  • время загрузки
  • событие, на котором произошёл сбой

Рекомендуется централизованная отправка ошибок:

function logLottieError(context) {
  fetch('/log', {
    method: 'POST',
    body: JSON.stringify(context),
    headers: { 'Content-Type': 'application/json' }
  });
}

Типовые сценарии отказов

Пустой контейнер

Анимация инициализируется без DOM-элемента:

  • отсутствует контейнер
  • DOM ещё не загружен

Результат — невозможность построения рендера без явного исключения.

Конфликт повторной инициализации

При повторном вызове loadAnimation без уничтожения предыдущего экземпляра:

  • утечка памяти
  • дублирование canvas/svg узлов
  • неконсистентное состояние анимации

Несовместимость версий Bodymovin

JSON может быть экспортирован из версии After Effects плагина, несовместимой с текущим Lottie Web:

  • отсутствующие свойства эффектов
  • изменённые структуры выражений
  • некорректные интерполяции

Поведение при частично повреждённых данных

При наличии не критичных ошибок Lottie Web:

  • игнорирует некорректные слои
  • пропускает отсутствующие ключевые кадры
  • продолжает рендеринг доступной части композиции

Это приводит к визуально «обрезанным» анимациям без явных ошибок в консоли.

Инструменты отладки

Используются следующие подходы:

  • включение verbose-логов в браузере
  • инспекция JSON перед загрузкой
  • проверка структуры через валидаторы Bodymovin
  • анализ событийной цепочки data_failed → DOMLoaded

Особое внимание уделяется моменту перехода между состояниями загрузки, так как именно там чаще всего фиксируются скрытые сбои.

Оглавление