Анимации Lottie

Lottie-анимации хранятся в формате JSON. Формат применяют для интерактивных элементов интерфейса: загрузочных экранов, индикаторов и других визуальных эффектов. Анимации не зависят от разрешения экрана и не нагружают сеть, в отличие от видео и растровых изображений.

В Bitrix Framework на базе библиотеки Lottie 5.13 доступно расширение ui.lottie. Расширение позволяет подключать анимации в интерфейсе и управлять воспроизведением из JavaScript-кода.

Подключить расширениеПодключить расширение

Подключите расширение ui.lottie в шаблон компонента или страницы.

В JavaScript-коде:

import {Lottie} from 'ui.lottie';

В PHP-коде:

\Bitrix\Main\UI\Extension::load('ui.lottie');

После подключения используйте объект BX.UI.Lottie для загрузки анимации.

Загрузить анимациюЗагрузить анимацию

Вызовите метод BX.UI.Lottie.loadAnimation() и передайте параметры в виде объекта.

• container — HTML-элемент, в который нужно вставить анимацию. Обязательный параметр.

• path — путь к JSON-файлу с анимацией. Используйте, если файл загружается по URL. Файл должен быть доступен браузеру.

• animationData — данные анимации в виде загруженного JSON-объекта. Альтернатива параметру path.

• renderer — тип отрисовки. Возможные значения: svg, canvas, html. Для векторной графики используйте svg.

• loop — зацикливание анимации. Передайте true для бесконечного повтора или число для фиксированного количества циклов.

• autoplay — автовоспроизведение. Возможные значения: true — воспроизведение сразу после загрузки, false — по событию.

• name — имя экземпляра анимации. Укажите имя, чтобы управлять анимацией через BX.UI.Lottie.play(name) и аналогичные методы.

Для загрузки анимации передайте один источник данных: path или animationData.

Пример вызова:

const animation = BX.UI.Lottie.loadAnimation({
    container: document.getElementById('lottie-container'),
    path: '/local/assets/animations/loader.json',
    renderer: 'svg',
    loop: true,
    autoplay: true
});

animation.addEventListener('data_failed', () => {
    console.error('Не удалось загрузить Lottie-анимацию');
});

Передать данные анимацииПередать данные анимации

Используйте параметр animationData, когда JSON-объект уже получен из API или встроен в JavaScript-код. Такой способ не требует отдельного файла с анимацией.

В примере код загружает анимацию из переменной animationData. Перед вызовом loadAnimation() подставьте в нее JSON-объект Lottie.

<?php
\Bitrix\Main\UI\Extension::load('ui.lottie');
?>

<div id="lottie-container" style="width: 120px; height: 120px;"></div>

<script>
BX.ready(() => {
    const container = document.getElementById('lottie-container');
    const animationData = {
        // JSON-объект Lottie-анимации
    };

    if (!container)
    {
        return;
    }

    const animation = BX.UI.Lottie.loadAnimation({
        container,
        animationData,
        renderer: 'svg',
        loop: true,
        autoplay: true,
    });

    animation.addEventListener('data_failed', () => {
        console.error('Не удалось обработать Lottie-анимацию');
    });
});
</script>

Настроить анимациюНастроить анимацию

Метод loadAnimation возвращает объект AnimationItem. Используйте методы объекта AnimationItem, чтобы управлять анимацией программно.

• play() — запускает воспроизведение.

• stop() — останавливает воспроизведение и возвращает к первому кадру.

• pause() — приостанавливает на текущем кадре.

• togglePause() — переключает паузу.

• setSpeed(speed) — изменяет скорость. Значение 1 — нормальная скорость, 0.5 — вдвое медленнее, 2 — вдвое быстрее.

• setDirection(direction) — меняет направление. Значение 1 — обычное направление, -1 — обратное направление.

• goToAndStop(value, isFrame) — переходит к указанному времени или кадру, если isFrame принимает true, и останавливает воспроизведение.

• goToAndPlay(value, isFrame) — переходит к указанному времени или кадру, если isFrame принимает true, и продолжает воспроизведение.

Удалить анимацию и освободить памятьУдалить анимацию и освободить память

Удалите анимацию из DOM и остановите все внутренние таймеры, когда анимация больше не нужна.

// Полностью уничтожить экземпляр, например, при смене страницы
animation.destroy();

Подписаться на событияПодписаться на события

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

• complete — анимация завершена.

• loopComplete — завершен очередной цикл, актуально при loop: true.

• enterFrame — событие на каждый кадр.

• drawnFrame — кадр отрендерен и отображен на экране.

• segmentStart — смена сегмента анимации.

• config_ready — конфигурация загружена.

• data_ready — JSON с анимацией загружен и обработан.

• DOMLoaded — анимация добавлена в DOM-дерево страницы.

• destroy — анимация удалена.

• data_failed — произошла ошибка при загрузке или обработке данных анимации.

• loaded_images — все внешние изображения успешно загружены.

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

animation.addEventListener('loopComplete', () => {
    console.log('Завершен один цикл');
});