Свойства объекта конфигурации

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

Контейнер определяет DOM-элемент, в который будет внедрена анимация. Внутри него создаётся либо <svg>, либо <canvas>, либо HTML-структура в зависимости от выбранного рендерера.

Ключевые особенности:

  • принимает ссылку на элемент DOM
  • используется как корневой узел для всех визуальных слоёв
  • управляет областью отрисовки и размерами
container: document.getElementById('animation')

renderer

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

Основные значения:

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

Выбор рендерера влияет на:

  • масштабируемость графики
  • производительность на слабых устройствах
  • поддержку сложных эффектов
renderer: 'svg'

loop

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

Варианты поведения:

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

При числовом значении внутренний счётчик уменьшает количество циклов до остановки.

loop: true

autoplay

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

Поведение:

  • true — запуск сразу после инициализации
  • false — ожидание ручного запуска через API
autoplay: false

animationData

Содержит JSON-структуру анимации, экспортированную из Adobe After Effects через Bodymovin. Этот объект полностью описывает сцену, слои, ключевые кадры и эффекты.

Особенности:

  • используется вместо загрузки по URL
  • полностью самодостаточен
  • не требует сетевых запросов

Структура включает:

  • layers — слои композиции
  • assets — внешние ресурсы
  • fr — частота кадров
  • w, h — размеры композиции
animationData: myAnimationJson

path

Определяет URL к JSON-файлу анимации. Используется вместо animationData, когда требуется загрузка из внешнего источника.

Характеристики:

  • поддерживает относительные и абсолютные пути
  • требует сетевого запроса
  • может кешироваться браузером
path: '/animations/loading.json'

name

Идентификатор экземпляра анимации. Используется для управления несколькими анимациями в одном окружении через глобальный объект управления.

Свойства:

  • уникальность не обязательна, но влияет на удобство отладки
  • применяется для поиска экземпляра
  • упрощает управление группами анимаций
name: 'preloaderAnimation'

rendererSettings

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

preserveAspectRatio

Определяет сохранение пропорций при масштабировании SVG-контента. Управляет тем, как анимация вписывается в контейнер.

Основные режимы:

  • xMidYMid meet — сохранение пропорций с вписыванием
  • xMinYMin slice — заполнение с обрезкой
rendererSettings: {
  preserveAspectRatio: 'xMidYMid meet'
}

clearCanvas

Используется в canvas-рендерере для очистки холста перед каждым кадром. Влияет на производительность и визуальные артефакты.

  • true — полная очистка перед рендером
  • false — накопительный режим отрисовки

progressiveLoad

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

  • снижает время первого рендера
  • полезно для тяжёлых JSON-анимаций

hideOnTransparent

Управляет видимостью canvas при полной прозрачности слоя.

  • true — скрытие элемента при прозрачности
  • false — сохранение DOM-узла в потоке

className

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

className: 'lottie-player'

initialSegment

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

Формат:

  • массив из двух чисел [startFrame, endFrame]

Особенности:

  • ограничивает диапазон проигрывания
  • влияет только на текущий цикл
  • не изменяет структуру данных
initialSegment: [0, 60]

assetsPath

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

Характеристики:

  • влияет на загрузку bitmap-ресурсов
  • используется при миграции между окружениями
  • поддерживает относительные пути
assetsPath: '/static/lottie/assets/'

параметры времени и кадров

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

Основные элементы временной модели:

  • кадровая частота (fr)
  • длительность композиции
  • сегменты воспроизведения

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

взаимодействие конфигурации с жизненным циклом

Конфигурационный объект используется только на этапе инициализации, после чего формируется экземпляр анимации. Последующие изменения выполняются через API, но не через повторную передачу конфигурации.

Поведение после создания:

  • container остаётся фиксированным
  • renderer не изменяется
  • animationData не пересобирается
  • параметры воспроизведения могут корректироваться через методы управления

структура типового объекта конфигурации

lottie.loadAnimation({
  container: document.getElementById('animation'),
  renderer: 'svg',
  loop: true,
  autoplay: true,
  name: 'mainAnimation',
  path: '/animations/data.json',
  rendererSettings: {
    preserveAspectRatio: 'xMidYMid meet'
  }
})
Оглавление