Lottie-анимации

Расширение lottie показывает Lottie-анимацию в элементе gif-image вместо GIF-изображения.

Для подключения анимации к gif-изображению заполните массив extensions:

{
  "extensions": [
    {
      "id": "lottie",
      "params": {
        "lottie_url": "https://assets9.lottiefiles.com/packages/lf20_edpg3c3s.json",
        "repeat_count": 3,
        "repeat_mode": "restart"
      }
    }
  ]
}

Примечание

Поведение параметра repeat_count

repeat_count: 0 — анимация проигрывается один раз
repeat_count: 1 — анимация проигрывается два раза
repeat_count: N — анимация проигрывается N+1 раз
repeat_count: -1 — бесконечное зацикливание

Параметры

Параметры	Описание
`id`	Идентификатор расширения.
`lottie_url`	Обязательная ссылка на Lottie JSON, если не задан параметр `lottie_json`. На Android может работать по схемам `asset:{address}` или `res:{address}` для встроенных ресурсов. Связывание ресурсов по этим схемам происходит через зависимость `DivLottieRawResProvider`, которая передается в `DivLottieExtensionHandler`. Предзагрузка анимации на Android выполняется для ссылок со схемами `http` и `https`.
`lottie_json`	Обязательный параметр, если не задана ссылка `lottie_url`. Содержит Lottie JSON в виде объекта. Задавайте только один из параметров `lottie_url` и `lottie_json`: если заданы оба, выбор источника зависит от платформы.
`repeat_count`	Количество повторов анимации. Для бесконечного количества повторов используйте значение `-1`. Значение по умолчанию зависит от платформы, поэтому задавайте параметр явно.
`repeat_mode`	Действие после окончания анимации. Может принимать значения: `restart` — анимация начинается сначала; `reverse` — анимация идет покадрово в обратном порядке. По умолчанию: `restart`.
`repeats`	Этапы воспроизведения с отдельными диапазонами кадров (только для Android). См. Этапы воспроизведения.
`is_playing`	Управляет автоматическим воспроизведением анимации при инициализации. Если установлено значение `false`, анимация не будет запускаться автоматически. Если значение задано выражением, его изменение приостанавливает или продолжает воспроизведение. По умолчанию: `true`.
`safe_mode`	Если установлено значение `true`, ошибка при отрисовке кадра анимации не приводит к аварийному завершению приложения: такой кадр не отображается (только для Android). По умолчанию: `false`.

Параметры lottie_url, repeat_count, repeat_mode и is_playing поддерживают выражения.

Этапы воспроизведения

На Android анимацию можно разделить на этапы. Каждый этап проигрывает свой диапазон кадров заданное число раз, после чего начинается следующий этап. Этапы перечисляются в массиве repeats:

Пример

{
  "extensions": [
    {
      "id": "lottie",
      "params": {
        "lottie_url": "https://assets9.lottiefiles.com/packages/lf20_edpg3c3s.json",
        "repeat_count": -1,
        "repeats": [
          {
            "repeat_count": 0,
            "min_frame": 0,
            "max_frame": 30
          },
          {
            "repeat_count": -1,
            "repeat_mode": "restart",
            "min_frame": 30,
            "max_frame": 90
          }
        ]
      }
    }
  ]
}

В этом примере кадры с 0 по 30 проигрываются один раз, после чего кадры с 30 по 90 повторяются бесконечно.

Параметры этапа	Описание
`repeat_count`	Количество повторов этапа. Значения задаются так же, как для параметра `repeat_count` расширения. По умолчанию: `1`.
`repeat_mode`	Действие после окончания прохода: `restart` или `reverse`. По умолчанию: `restart`.
`min_frame`	Кадр, с которого начинается этап. По умолчанию: первый кадр анимации.
`max_frame`	Кадр, на котором заканчивается этап. По умолчанию: последний кадр анимации.

Если массив repeats содержит хотя бы один этап, параметры repeat_count и repeat_mode расширения на Android не используются. На остальных платформах массив repeats не учитывается: анимация проигрывается целиком по параметрам repeat_count и repeat_mode.

Масштабирование

Анимация масштабируется по свойству scale элемента gif-image, так же как GIF-изображение.

Управление Lottie через действия

Используйте extension_action, чтобы отправить команду расширению lottie на элементе с указанным div_id. Команду передавайте в payload внешнего действия, на одном уровне с typed.

start перематывает анимацию и запускает воспроизведение с начала; stop перематывает её в начало и оставляет остановленной. Например, чтобы перезапустить анимацию:

{
  "log_id": "start_lottie",
  "typed": {
    "type": "extension_action",
    "div_id": "my_div",
    "extension_id": "lottie"
  },
  "payload": {
    "type": "start"
  }
}

Чтобы остановить её, замените "type": "start" в payload на "type": "stop".

После команды start или stop воспроизведением управляют команды: значение is_playing на него не влияет.

Подключение

Пример подключения обработчика расширения на Android и в Web приведен в разделе Подключение.

На iOS DivKit не зависит от библиотеки воспроизведения Lottie. Передайте в LottieExtensionHandler фабрику, которая реализует протокол AsyncSourceAnimatableViewFactory и создает view для воспроизведения анимации:

let lottieExtensionHandler = LottieExtensionHandler(
  factory: LottieAnimationFactory(),
  requester: requester
)

factory — фабрика view анимации. Она же определяет, сколько раз проигрывается анимация при заданных repeat_count и repeat_mode. Пример фабрики для библиотеки lottie-ios есть в приложении DivKit Playground.
requester — объект URLResourceRequesting, который загружает файл анимации по ссылке из lottie_url.

Чтобы на iOS работали команды start и stop, view анимации должно реализовывать протокол LottiePlaybackControlling.

Узнать больше

Вы можете обсуждать интересующие вас темы в сообществе пользователей DivKit в Telegram: https://t.me/divkit_community_ru.

Репозиторий DivKit

Была ли статья полезна?

Расширения

Увеличение жестом