Параметры конфигурации

Инициализация Lottie-анимации в веб-приложении строится вокруг функции lottie.loadAnimation, принимающей объект конфигурации. Этот объект определяет источник анимации, способ её рендеринга, поведение цикла и режимы воспроизведения.

Ключевые параметры верхнего уровня задают фундамент поведения анимации.

container DOM-элемент, в который будет встроена анимация. Может быть как div, так и любой другой HTML-элемент. Именно в этот контейнер библиотека монтирует SVG, canvas или HTML-структуру в зависимости от выбранного рендерера.

renderer Определяет технологию отрисовки:

  • svg — векторный рендеринг, основной вариант
  • canvas — растровый рендеринг через Canvas API
  • html — DOM-элементы (используется реже, в специфических сценариях)

Выбор рендерера влияет на производительность, качество масштабирования и поддержку эффектов.

loop Управление повтором анимации:

  • true — бесконечный цикл
  • false — однократное воспроизведение
  • число — фиксированное количество повторов

Механизм цикла реализуется на уровне временной шкалы композиции After Effects-экспорта.

autoplay Флаг автоматического запуска после загрузки. При значении true анимация стартует сразу после инициализации, без вызова play().

animationData Объект JSON, содержащий полную структуру Lottie-анимации. Используется при загрузке данных напрямую, без обращения к внешнему файлу.

path Путь к JSON-файлу анимации. Используется при загрузке с сервера или локального ресурса. Взаимоисключаем с animationData.

Источники анимации и режимы загрузки

Lottie Web поддерживает два основных способа получения данных:

  • загрузка через path, где библиотека выполняет HTTP-запрос;
  • передача через animationData, когда JSON уже доступен в памяти приложения.

Приоритет всегда отдаётся animationData, если оба параметра указаны.

В системах с динамической подгрузкой контента path часто комбинируется с кешированием, чтобы снизить нагрузку на сеть и ускорить повторные рендеры.

Параметры управления временем и состоянием

Хотя базовые свойства loop и autoplay определяют поведение старта и окончания, дополнительная логика может управляться через программный API, однако часть временных параметров задаётся косвенно через конфигурацию.

initialSegment Позволяет ограничить воспроизведение определённым диапазоном кадров:

initialSegment: [10, 60]

Используется для запуска части анимации без модификации JSON.

Настройки рендеринга

Более глубокая настройка поведения визуализации задаётся через объект rendererSettings. Этот блок критически важен при оптимизации производительности и адаптации под разные устройства.

rendererSettings включает следующие параметры:

preserveAspectRatio

Управляет масштабированием контента внутри контейнера. Поведение аналогично SVG-атрибуту preserveAspectRatio. Позволяет контролировать:

  • растяжение
  • центрирование
  • обрезку

Типичные значения:

  • xMidYMid meet — сохранение пропорций с вписыванием
  • xMidYMid slice — заполнение контейнера с возможной обрезкой

clearCanvas

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

progressiveLoad

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

hideOnTransparent

Автоматически скрывает элементы с полной прозрачностью. Оптимизация снижает количество отрисовываемых объектов.

className

Добавляет CSS-класс к контейнеру анимации. Используется для стилизации и интеграции с внешними системами верстки.

id

Задаёт уникальный идентификатор для корневого элемента анимации. Применяется при управлении несколькими экземплярами на одной странице.

context

Используется исключительно в canvas-режиме. Позволяет передать уже созданный CanvasRenderingContext2D, что даёт контроль над внешним canvas-слоем приложения.

imagePreserveAspectRatio

Регулирует поведение растровых изображений внутри SVG-рендера. Влияет на корректность масштабирования встроенных bitmap-ассетов.

Работа с разрешением и плотностью пикселей

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

При использовании svg рендерера масштабирование происходит без потерь, так как все элементы остаются векторными.

В canvas-режиме применяется масштабирование через devicePixelRatio, что позволяет сохранить чёткость на Retina-дисплеях, но увеличивает нагрузку на GPU и CPU.

Поведение загрузчика и асинхронность

При использовании path загрузка анимации выполняется асинхронно. В этот момент создаётся внутренний запрос, результат которого парсится в структуру слоёв и временной шкалы.

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

Взаимодействие с DOM и структурой контейнера

Контейнер, переданный в container, становится корневым узлом для всех визуальных элементов анимации. В зависимости от рендерера структура внутри контейнера различается:

  • SVG-режим создаёт <svg> дерево
  • Canvas-режим создаёт <canvas> элемент
  • HTML-режим формирует набор DOM-элементов с абсолютным позиционированием

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

Конфигурационные зависимости и ограничения

Некоторые параметры взаимно исключают друг друга:

  • path и animationData не используются одновременно в логике загрузки
  • context применим только к canvas
  • rendererSettings частично игнорируются в зависимости от выбранного рендерера

Также поведение некоторых параметров зависит от версии экспорта After Effects, так как структура JSON может различаться.

Особенности поведения при повторной инициализации

При повторном вызове lottie.loadAnimation в одном контейнере без предварительного уничтожения предыдущего экземпляра создаётся конфликт DOM-структур. Это связано с тем, что конфигурация не содержит автоматического механизма очистки контейнера.

Повторная инициализация требует нового DOM-узла или явного удаления предыдущей анимации через API экземпляра.

Управление масштабированием и адаптацией

Система масштабирования Lottie Web основана на внутреннем пересчёте координат всех слоёв относительно размеров контейнера. При изменении размеров контейнера пересчёт выполняется автоматически, если не отключены соответствующие механизмы обновления.

В SVG-режиме масштабирование остаётся декларативным, что делает поведение предсказуемым при изменении layout.

В Canvas-режиме масштабирование связано с перерисовкой кадров, что может влиять на производительность при частых resize-событиях.

Оглавление