Методы экземпляра AnimationItem

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

Базовый набор методов отвечает за запуск, приостановку и остановку анимации. Эти операции изменяют внутренний таймер и состояние текущего кадра, не разрушая контекст анимации.

play() Запускает или возобновляет воспроизведение анимации с текущего кадра. Если анимация была поставлена на паузу, продолжение происходит без сброса состояния.

• не сбрасывает текущий прогресс
• учитывает направление воспроизведения
• активирует внутренний requestAnimationFrame цикл

pause() Приостанавливает анимацию, фиксируя текущий кадр. Таймер воспроизведения останавливается, но состояние сохраняется.

• сохраняет текущий frame
• не изменяет прогресс композиции
• может быть продолжена через play()

stop() Останавливает воспроизведение и сбрасывает анимацию в начальное состояние.

• устанавливает текущий кадр в firstFrame
• останавливает цикл обновления
• возвращает анимацию в исходную позицию

В отличие от pause, метод stop изменяет логическое состояние прогресса, а не только приостанавливает его.

Навигация по временной шкале

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

goToAndPlay(value, isFrame) Перемещает анимацию к указанному времени или кадру и сразу запускает воспроизведение.

• value — целевое значение (в кадрах или миллисекундах)
• isFrame — булев флаг, определяющий интерпретацию значения

Поведение зависит от типа шкалы:

• при isFrame = true используется индекс кадра
• при isFrame = false используется время в миллисекундах

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

goToAndStop(value, isFrame) Аналогичен goToAndPlay, но фиксирует анимацию на указанном кадре без запуска воспроизведения.

• переводит состояние в паузу
• обновляет текущий кадр
• не активирует цикл play

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

Управление скоростью воспроизведения

setSpeed(speed) Изменяет коэффициент скорости воспроизведения анимации.

• 1 — нормальная скорость
• < 1 — замедление
• > 1 — ускорение
• отрицательные значения допускаются и изменяют направление воспроизведения

Скорость применяется к внутреннему дельта-таймеру, влияя на шаг изменения текущего кадра.

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

Управление направлением

setDirection(direction) Устанавливает направление воспроизведения анимации.

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

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

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

Управление субкадрами

setSubframe(useSubframes) Определяет, используется ли субкадровая интерполяция.

• true — включение субкадров (более плавное движение)
• false — дискретные кадры

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

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

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

destroy() Полностью уничтожает экземпляр анимации и освобождает связанные ресурсы.

• удаляет обработчики событий
• прекращает requestAnimationFrame цикл
• освобождает DOM-связанные ссылки
• очищает память, занятую слоями и рендерером

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

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

Управление текущим состоянием без воспроизведения

Некоторые методы косвенно влияют на состояние анимации через модификацию параметров воспроизведения, не запуская цикл.

• stop() — сброс состояния
• pause() — фиксация текущего кадра
• goToAndStop() — установка произвольного состояния
• setSpeed() — изменение динамики временной оси
• setDirection() — изменение логики прогрессии

Комбинации этих методов позволяют формировать статические состояния анимации без необходимости проигрывания.

Взаимодействие методов между собой

Поведение методов AnimationItem не изолировано — они изменяют общие внутренние параметры экземпляра:

• временная шкала (time)
• индекс кадра (currentFrame)
• направление (direction)
• коэффициент скорости (playSpeed)
• состояние воспроизведения (isPaused, isStopped)

Например, вызов setSpeed во время активного play не прерывает воспроизведение, а лишь модифицирует шаг изменения времени. Аналогично, setDirection мгновенно изменяет знак приращения кадров, не сбрасывая прогресс.

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

Особенности реализации в Lottie Web

Методы экземпляра работают поверх абстракции рендерера (Canvas, SVG или HTML), не взаимодействуя напрямую с DOM-элементами за исключением уничтожения (destroy). Это означает, что управление через AnimationItem остается единым независимо от выбранного renderer.

Внутренний цикл обновления основан на requestAnimationFrame, а методы управления лишь модифицируют параметры, которые интерпретируются на следующем кадре отрисовки.

Такая архитектура обеспечивает предсказуемость поведения:

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