Изменения в API между версиями

Библиотека Lottie Web исторически развивалась как JavaScript-реализация рендеринга анимаций After Effects через JSON-формат Bodymovin. Архитектура API сохраняет ядро, но между версиями происходили существенные изменения в конфигурации и поведении ключевых методов, особенно в области инициализации, управления проигрыванием и работы с рендерами.

Инициализация и загрузка анимации

lottie.loadAnimation и структура конфигурации

Базовый метод загрузки анимации остаётся центральным элементом API:

lottie.loadAnimation(params)

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

Ключевые изменения конфигурации

1. renderer

Ранее поддерживались значения:

  • "svg"
  • "canvas"
  • "html"

В новых версиях поведение унифицировано:

  • "svg" стал наиболее стабильным и функционально полным
  • "canvas" получил оптимизацию производительности, но ограничение по сложным эффектам
  • "html" фактически считается устаревшим и используется редко

2. animationData vs path

Изначально допускалось неявное смешивание загрузки по URL и через JSON.

Современная модель строго разделяет:

  • animationData — уже загруженный JSON
  • path — URL к JSON-файлу

Одновременное использование считается конфликтным поведением, приоритет зависит от версии, но в актуальной реализации предпочтение отдаётся animationData.

3. container

Ранее контейнер мог быть строковым селектором. Позднее введена строгая рекомендация использовать DOM-элемент:

container: document.getElementById('app')

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

4. loop и autoplay

Изначально:

  • loop: true/false
  • autoplay: true/false

Позднее добавлена поддержка расширенных значений:

  • loop: number — количество циклов
  • loop: boolean | number | object (в некоторых сборках)

Поведение autoplay стало зависеть от внутреннего состояния инстанса и очереди событий загрузки.

Изменения в API управления воспроизведением

Базовые методы проигрывания

Основные методы сохраняются, но их поведение менялось между версиями:

  • play()
  • pause()
  • stop()

stop()

Ранние версии:

  • сбрасывал анимацию в начало
  • очищал текущие сегменты

Поздние версии:

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

Управление сегментами

playSegments

animation.playSegments([10, 50], true)

Изменения между версиями:

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

Навигация по времени

goToAndPlay и goToAndStop

Сигнатуры:

goToAndPlay(value, isFrame)
goToAndStop(value, isFrame)

Изменения:

  • ранее value интерпретировался неоднозначно (frame/time)
  • позже добавлен строгий флаг isFrame
  • устранена автоматическая конвертация времени в кадры

Управление направлением и скоростью

setSpeed

Ранее скорость применялась только к текущему проигрыванию.

Позже:

  • стала сохраняться как состояние инстанса
  • влияет на последующие play() без переинициализации

setDirection

Поведение изменилось с “моментального разворота” на:

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

Событийная модель

addEventListener и события анимации

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

  • enterFrame
  • loopComplete
  • complete
  • segmentStart

Изменения между версиями

1. enterFrame

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

Позднее:

  • синхронизировано с requestAnimationFrame
  • введена более стабильная частота вызова

2. DOMLoaded

В старых версиях использовалось как основной сигнал готовности.

В новых версиях:

  • разделено на внутреннюю и внешнюю готовность
  • заменено на комбинацию loaded_images и DOMLoaded (в зависимости от рендера)

3. complete

Поведение изменено для loop-режима:

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

Изменения в рендерерах

SVG renderer

SVG стал основным и наиболее стабильным рендерером.

Изменения:

  • переработан механизм DOM-инъекции
  • оптимизирована работа с <path> и <mask>
  • улучшена поддержка gradient и stroke animation

Canvas renderer

Canvas-движок подвергся нескольким переработкам:

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

Изменение API практически не затронуло внешний интерфейс, но повлияло на поведение визуализации.

HTML renderer (устаревший)

В ранних версиях использовался для fallback-рендеринга через DOM-элементы.

Позднее:

  • помечен как deprecated
  • исключён из некоторых сборок
  • перестал поддерживать часть эффектов (blur, masks, precompositions)

Изменения в обработке ассетов

assetsPath

Ранее использовался как простой префикс для загрузки изображений.

Позднее:

  • добавлена поддержка функций-resolver’ов
  • возможность динамической подмены путей

imagePreloader

Изменено поведение:

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

API экземпляра анимации

destroy()

Изменения:

  • ранние версии не полностью освобождали память (особенно в canvas)

  • поздние версии добавили:

    • очистку requestAnimationFrame
    • удаление слушателей событий
    • освобождение SVG DOM узлов

resize()

Поведение:

  • ранее требовал ручного вызова при изменении контейнера
  • позже частично автоматизирован через ResizeObserver (в некоторых сборках)

setSubframe

Изменения:

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

Изменения в структуре экспорта

Глобальный объект lottie

Ранее:

window.lottie

Позже:

  • поддержка ES modules:
import lottie from 'lottie-web'
  • добавлены именованные экспорты в некоторых сборках

Обратная совместимость и устаревшие методы

Удалённые или изменённые методы

  • setVolume — отсутствует (звук не поддерживается по архитектуре)
  • addEventListener без namespace — заменён на строгую подписку событий
  • неявные глобальные настройки рендера — удалены

Типизация и TypeScript изменения

В ранних версиях отсутствовала полноценная типизация.

Позднее добавлены:

  • интерфейсы AnimationItem
  • строгие типы RendererType
  • типизированный ILottieConfig

Изменения:

  • ужесточение типов loop и autoplay
  • обязательность container в конфигурации
  • уточнение типов событий и callback-ов

Поведение внутреннего таймлайна

Кадровая модель

Ранее:

  • допускались дробные кадры без строгой синхронизации

Позднее:

  • введена нормализация времени
  • синхронизация с FPS из JSON
  • исправлены расхождения между AE и runtime

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

С каждой версией изменялась внутренняя архитектура:

  • оптимизация tree traversal анимационных слоёв
  • кэширование path-data
  • батчинг DOM-операций в SVG

Итоговые направления эволюции API

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