Типы событий и их параметры

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

Практически все события Lottie Web передают объект события, содержащий базовый набор полей и ссылку на экземпляр анимации.

Базовая структура

Типичный event-объект включает:

  • animationItem — ссылка на внутренний объект анимации
  • type — строковое обозначение события
  • currentTime — текущее время воспроизведения (секунды)
  • totalTime — общая длительность анимации (секунды)
  • currentFrame — текущий кадр
  • totalFrames — общее количество кадров
  • direction — направление воспроизведения (1 вперёд, -1 назад)

Набор полей может варьироваться в зависимости от типа события. Некоторые события содержат только animationItem и type, без временных данных.

События загрузки и инициализации

data_ready

Срабатывает после успешной загрузки JSON-анимации и её первичной обработки.

Параметры event:

  • animationItem — объект анимации
  • type = "data_ready"

В этот момент данные уже распарсены, но DOM-элементы рендера могут ещё не быть готовы.

config_ready

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

Параметры event:

  • animationItem
  • type = "config_ready"

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

DOMLoaded

Фиксирует момент полной готовности DOM-структуры, используемой для рендеринга SVG или HTML-слоёв.

Параметры event:

  • animationItem
  • type = "DOMLoaded"

Не содержит временных метрик, так как относится к стадии построения DOM.

data_failed / error

Событие ошибки загрузки или обработки данных.

Параметры event:

  • animationItem
  • type = "error"
  • error — текст или объект ошибки

В некоторых реализациях также присутствует:

  • message — описание ошибки
  • stack — стек вызовов (реже)

События воспроизведения

enterFrame

Ключевое событие, вызываемое на каждом кадре анимации.

Параметры event:

  • animationItem
  • type = "enterFrame"
  • currentTime
  • totalTime
  • currentFrame
  • totalFrames
  • direction

Дополнительно может присутствовать:

  • progress — нормализованное значение от 0 до 1

Особенность данного события заключается в высокой частоте вызова, что требует минимальной логики внутри обработчика.

loopComplete

Срабатывает при завершении одного цикла воспроизведения.

Параметры event:

  • animationItem
  • type = "loopComplete"
  • loopCount — номер завершённого цикла
  • totalLoops — общее число циклов (если задано)

Если режим зацикливания установлен как бесконечный, totalLoops может отсутствовать.

complete

Событие финального завершения анимации.

Параметры event:

  • animationItem
  • type = "complete"

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

segmentStart

Срабатывает при переходе к новому сегменту анимации.

Параметры event:

  • animationItem
  • type = "segmentStart"
  • firstFrame — начальный кадр сегмента
  • lastFrame — конечный кадр сегмента
  • totalFrames — длина сегмента

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

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

destroy

Срабатывает при уничтожении экземпляра анимации.

Параметры event:

  • animationItem
  • type = "destroy"

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

Структура animationItem в событиях

Практически каждое событие содержит ссылку animationItem, представляющую внутреннее состояние анимации.

Ключевые поля:

  • name — имя экземпляра
  • frameRate — частота кадров
  • playDirection — текущее направление воспроизведения
  • isPaused — состояние паузы
  • isLoaded — статус загрузки
  • currentRawFrame — текущий «сырой» кадр
  • firstFrame / lastFrame — границы текущего диапазона
  • frameMult — коэффициент масштабирования кадров

Также доступны методы управления:

  • play()
  • pause()
  • stop()
  • setSpeed()
  • goToAndPlay()
  • goToAndStop()
  • setDirection()

Через animationItem можно получать доступ к текущему renderer и данным композиции.

Особенности передачи параметров

Непостоянство структуры

Не все события гарантируют одинаковый набор полей. Например:

  • enterFrame содержит полный набор временных параметров
  • complete ограничивается идентификатором события
  • error расширяется полем error

Производительность событий

События делятся на две категории по нагрузке:

  • Высокочастотные: enterFrame
  • Событийные (редкие): data_ready, complete, loopComplete, segmentStart, destroy

Обработка высокочастотных событий требует минимизации вычислений внутри callback-функций.

Контекст рендера

В зависимости от режима (SVG, Canvas, HTML) animationItem может содержать разные внутренние реализации:

  • SVG-renderer предоставляет доступ к DOM-узлам
  • Canvas-renderer работает через пиксельный буфер
  • HTML-renderer использует DOM-слои

Это влияет на доступные свойства внутри animationItem, но не изменяет структуру событий.

Типизация событий (логическая модель)

Для упрощения обработки часто используется логическая группировка:

Инициализация

  • data_ready
  • config_ready
  • DOMLoaded

Воспроизведение

  • enterFrame
  • loopComplete
  • complete
  • segmentStart

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

  • destroy

Ошибки

  • error

Поведение событий при асинхронной загрузке

При загрузке через JSON или URL порядок событий обычно фиксирован:

  1. data_ready
  2. config_ready
  3. DOMLoaded (при наличии DOM-рендера)
  4. старт воспроизведения
  5. enterFrame (циклически)
  6. loopComplete (при цикличности)
  7. complete (при завершении)
  8. destroy (при удалении экземпляра)

Отклонения возможны при динамической подгрузке ассетов или изменении сегментов во время воспроизведения.

Практическая структура обработки событий

Внутренне обработчики регистрируются через:

  • addEventListener(type, callback)
  • removeEventListener(type, callback)

Тип события передаётся строкой, соответствующей имени события. Callback получает единый event-объект, структура которого определяется типом события и состоянием анимации.

Временные параметры и их интерпретация

currentFrame и currentTime

  • currentFrame — дискретное значение
  • currentTime — непрерывное значение в секундах

Соотношение зависит от frameRate:

currentTime = currentFrame / frameRate

direction

  • 1 — прямое воспроизведение
  • -1 — обратное воспроизведение

В enterFrame направление влияет на изменение currentFrame.

Поведение событий при сегментированном воспроизведении

При использовании сегментов (playSegments) параметры событий ограничиваются текущим диапазоном:

  • firstFrame и lastFrame определяют локальные границы
  • currentFrame считается относительно сегмента
  • totalFrames соответствует длине сегмента, а не всей анимации

Итоговая модель взаимодействия событий

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

Оглавление