Событие complete

Поведение анимации и момент завершения

В библиотеке lottie-web каждое воспроизведение анимации проходит через полный жизненный цикл: загрузка, инициализация, проигрывание кадров и завершение. Событие complete срабатывает в момент, когда анимация доходит до своего конечного кадра при нормальном направлении воспроизведения.

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

Механизм генерации события

Внутри движка Lottie Web анимация управляется через внутренний таймер и систему кадров. При каждом обновлении состояния проверяется текущая позиция:

  • текущий кадр увеличивается в зависимости от fps и времени
  • сравнивается с конечным кадром (totalFrames)
  • при достижении конца инициируется событие завершения

Событие complete срабатывает только при условии, что направление воспроизведения — прямое (direction === 1) и цикл не активирован или завершил текущую итерацию.

Подключение обработчика события

Обработчик события регистрируется через метод addEventListener или через onComplete в объекте анимации.

const animation = lottie.loadAnimation({
  container: document.getElementById('icon'),
  renderer: 'svg',
  loop: false,
  autoplay: true,
  path: 'animation.json'
});

animation.addEventListener('complete', () => {
  console.log('Анимация завершила воспроизведение');
});

Альтернативная форма:

animation.onCompl ete = function () {
  console.log('Завершение анимации');
};

Обе формы эквивалентны, однако addEventListener позволяет регистрировать несколько обработчиков одновременно.

Поведение при включённом loop

При активированном циклическом воспроизведении (loop: true) событие complete ведёт себя иначе. Оно срабатывает в конце каждого полного цикла, но анимация автоматически перезапускается.

const animation = lottie.loadAnimation({
  container: document.getElementById('looped'),
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: 'loop.json'
});

animation.addEventListener('complete', () => {
  console.log('Один цикл завершён');
});

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

Отличие от loopComplete

В Lottie Web существует ещё одно связанное событие — loopComplete. Оно срабатывает в момент завершения одного цикла, но только если используется параметр loop в виде числа или активирован бесконечный цикл.

Различие:

  • complete — завершение всей анимации или одного прохода при отсутствии loop
  • loopComplete — завершение одного цикла при циклическом воспроизведении

При loop: true оба события могут пересекаться в зависимости от версии библиотеки и конфигурации.

Влияние направления воспроизведения

Lottie поддерживает изменение направления через свойство setDirection. При обратном воспроизведении (direction === -1) событие complete срабатывает в момент достижения первого кадра.

animation.setDirection(-1);
animation.play();

animation.addEventListener('complete', () => {
  console.log('Обратное воспроизведение завершено');
});

Таким образом, термин «завершение» всегда относится к достижению крайней точки временной шкалы в текущем направлении.

Асинхронная природа события

Событие complete не блокирует поток выполнения и обрабатывается в рамках внутреннего цикла обновления. Это означает, что:

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

В сложных интерфейсах это важно учитывать при синхронизации UI-логики.

Частые сценарии использования

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

  • переключение интерфейсных состояний
  • запуск следующей анимации
  • активация интерактивных элементов
  • удаление или скрытие контейнера
animation.addEventListener('complete', () => {
  document.body.classList.add('animation-finished');
});

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

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

Удаление обработчика:

function onComplete() {
  console.log('завершено');
}

animation.addEventListener('complete', onComplete);
animation.removeEventListener('complete', onComplete);

Особенности при динамической загрузке

Если анимация загружается асинхронно через loadAnimation, событие complete становится доступным только после полной инициализации JSON и построения внутренних структур кадров. До этого момента регистрация событий возможна, но фактическое срабатывание произойдёт только после старта воспроизведения.

Синхронизация с другими событиями

В Lottie Web событие complete часто используется вместе с:

  • DOMLoaded — завершение построения DOM-структуры
  • enterFrame — обновление каждого кадра
  • data_ready — готовность данных анимации

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

Ограничения и нюансы реализации

Событие может не сработать в следующих случаях:

  • анимация остановлена через stop() до достижения конца
  • изменён текущий кадр через goToAndStop() на последнем этапе без запуска воспроизведения
  • разрушен экземпляр анимации до завершения цикла
  • используется кастомный рендерер с нестандартной логикой кадров

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

Оглавление