Кастомизация

Элемент extension — это блок данных, который позволяет изменять поведение и отображение элементов. Расширение можно добавлять к любому элементу.

Дополнительная логика описывается в обработчике расширения DivExtensionHandler.

Готовые расширения

Идентификатор	Описание	Исходный код
`pinch-to-zoom`	Увеличивает элемент.	Android iOS
`lottie`	Подключает Lottie-анимации к gif-image.	Android iOS Web
`input_autocorrection`	Управляет автокоррекцией текста в элементах input (только для iOS).	iOS
`rasterize`	Исправляет проблемы с отрисовкой вне экрана в overlap контейнерах (только для iOS).	iOS
`blur`	Добавляет эффект размытия к элементу (только для iOS).	iOS
`backdrop-effect`	Применяет сложные графические эффекты к фону элемента: размытие, преломление, коррекцию цвета и подсветку краев (только для Android).	Android

Подключение

Примечание

В качестве примера в этом разделе используется расширение Lottie.

Android

iOS

Web

build.gradle

dependencies {
    implementation "com.yandex.div:div-pinch-to-zoom:${versions.divkit}"
    implementation "com.airbnb.android:lottie:${versions.lottie}"
    implementation "com.yandex.div:div-lottie:${versions.lottie}"
}

В коде:

val pinchToZoomConfiguration = DivPinchToZoomConfiguration.Builder(this)
    .host(window)
    .dimColor(0xFF808080.toInt())
    .build()
val rawResProvider = object : DivLottieRawResProvider {
    override fun provideRes(url: String): Int? {
        if (url == "res://love") return R.raw.love_anim
        return null
    }
    override fun provideAssetFile(url: String): String? {
        if (url == "asset://banana") return "lottie/lottie_1.json"
        return null
    }
}
val divConfiguration = DivConfiguration.Builder(DefaultDivImageLoader(Container.imageManager))
    .experimentConfig(experimentConfig)
    .actionHandler(actionHandler)
    .divLogger(logger)
    .extension(DivPinchToZoomExtensionHandler(pinchToZoomConfiguration))
    .extension(DivLottieExtensionHandler(rawResProvider))
    .build()
val divContext = DivContext(baseContext = this, configuration = divConfiguration)
divView = DivView(divContext)

Обработчики расширений должны соответствовать протоколу DivExtensionHandler.

Для подключения обработчика передайте его в DivBlockModelingContext:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    PinchToZoomExtensionHandler(overlayView: rootView),
    SomeExtensionHandler()
  ]
)

import { lottieExtensionBuilder } from '@divkitframework/divkit/client';
import Lottie from 'lottie-web/build/player/lottie';

const map = new Map();

map.set('lottie', lottieExtensionBuilder(Lottie.loadAnimation));

render({
    id: 'test',
    target: element,
    json: {},
    extensions: map
});

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

Lottie в анимированном 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`. Может работать по схемам `asset:{address}` или `res:{address}` для встроенных ресурсов. Связывание ресурсов по этим схемам происходит через зависимость `DivLottieRawResProvider`, которая передается в `DivLottieExtensionHandler`. При использовании неподдерживаемых схем URL (не http/https/file/res) предзагрузка анимации будет пропущена с записью ошибки в лог.
`lottie_json`	Обязательный параметр, если не задана ссылка `lottie_url`. Содержит Lottie JSON.
`repeat_count`	Количество повторов анимации. Для бесконечного количества повторов используйте значение `-1`.
`repeat_mode`	Действие после окончания анимации. Может принимать значения: `restart` — анимация начинается сначала; `reverse` — анимация идет покадрово в обратном порядке.
`min_frame`	Минимальный кадр, с которого начинается анимация. Используется для сложных сценариев цикличного воспроизведения.
`is_playing`	Управляет автоматическим воспроизведением анимации при инициализации. Если установлено значение `false`, анимация не будет запускаться автоматически. По умолчанию: `true`.

Управление автокоррекцией текста

Для управления автокоррекцией текста в элементах input на iOS используйте расширение input_autocorrection:

{
  "extensions": [
    {
      "id": "input_autocorrection",
      "params": {
        "enabled": false
      }
    }
  ]
}

Параметры	Описание
`id`	Идентификатор расширения.
`enabled`	Управляет включением автокоррекции для поля ввода. Установите значение `false`, чтобы отключить автокоррекцию.

Автоматическая коррекция соотношения сторон изображений

Для автоматического кадрирования изображений в div-image до ожидаемого соотношения сторон используйте расширение aspect-correction (только для iOS):

{
  "extensions": [
    {
      "id": "aspect-correction",
      "params": {
        "aspect_tolerance": 0.001
      }
    }
  ]
}

Параметры	Описание
`id`	Идентификатор расширения.
`aspect_tolerance`	Допуск отклонения соотношения сторон (опционально). Если фактическое соотношение сторон отличается от ожидаемого менее чем на это значение, кадрирование не применяется. По умолчанию: 0.001.

Особенности работы:

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

Интеграция на iOS:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    AspectCorrectionExtensionHandler(aspectTolerance: 0.001)
  ]
)

Растеризация для исправления отрисовки вне экрана

Для исправления проблем с отрисовкой вне экрана в overlap контейнерах используйте расширение rasterize (только для iOS):

{
  "extensions": [
    {
      "id": "rasterize"
    }
  ]
}

Параметры	Описание
`id`	Идентификатор расширения.

Особенности работы:

Применяет растеризацию к блокам через layer.shouldRasterize = true
Использует UIScreen.main.scale для оптимального качества
Решает проблемы с отрисовкой вне экрана в overlap контейнерах

Интеграция на iOS:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    RasterizeExtensionHandler()
  ]
)

Эффект размытия

Для добавления эффекта размытия к элементу используйте расширение blur (только для iOS):

{
  "extensions": [
    {
      "id": "blur",
      "params": {
        "style": "regular"
      }
    }
  ]
}

Параметры

Описание

id

Идентификатор расширения.

style

Стиль эффекта размытия. Доступные значения:

extra_light — очень светлый
regular — обычный
prominent — выразительный
system_ultra_thin_material — ультратонкий материал
system_ultra_thin_material_light — ультратонкий материал (светлый вариант)
system_ultra_thin_material_dark — ультратонкий материал (темный вариант)
system_thin_material — тонкий материал
system_thin_material_light — тонкий материал (светлый вариант)
system_thin_material_dark — тонкий материал (темный вариант)
system_material — материал
system_material_light — материал (светлый вариант)
system_material_dark — материал (темный вариант)
system_thick_material — толстый материал
system_thick_material_light — толстый материал (светлый вариант)
system_thick_material_dark — толстый материал (темный вариант)
system_chrome_material — хром материал
system_chrome_material_light — хром материал (светлый вариант)
system_chrome_material_dark — хром материал (темный вариант)

Особенности работы:

Использует системные blur-эффекты iOS (UIBlurEffect)
Поддерживает как базовые стили, так и material-стили с вариантами для светлой и темной темы
Применяется ко всему элементу, к которому добавлено расширение

Интеграция на iOS:

DivBlockModelingContext(
  ...
  extensionHandlers: [
    BlurExtensionHandler()
  ]
)

Эффекты фона

Для применения графических эффектов к фону элемента используйте расширение backdrop-effect (только для Android):

{
  "extensions": [
    {
      "id": "backdrop-effect",
      "params": {
        "blur_radius": 10.0,
        "refraction_height": 5.0,
        "refraction_strength": 0.5,
        "chromatic_aberration": 0.3,
        "brightness": 1.2,
        "contrast": 1.1,
        "saturation": 0.9,
        "rim_highlight_angle": 45.0,
        "rim_highlight_fade": 0.5,
        "corner_radius": 16.0,
        "backdrop_scope": "card"
      }
    }
  ]
}

Параметры	Описание
`id`	Идентификатор расширения.
`blur_radius`	Радиус размытия фона в пикселях. Опциональный параметр.
`refraction_height`	Высота эффекта преломления. Опциональный параметр.
`refraction_strength`	Сила эффекта преломления (от 0.0 до 1.0). Опциональный параметр.
`chromatic_aberration`	Сила хроматической аберрации для эффекта преломления (от 0.0 до 1.0). Опциональный параметр.
`brightness`	Коэффициент яркости фона. Значение 1.0 — без изменений. Опциональный параметр.
`contrast`	Коэффициент контраста фона. Значение 1.0 — без изменений. Опциональный параметр.
`saturation`	Коэффициент насыщенности фона. Значение 1.0 — без изменений. Опциональный параметр.
`rim_highlight_angle`	Угол падения света для подсветки краев в градусах. Опциональный параметр.
`rim_highlight_fade`	Коэффициент затухания подсветки краев (от 0.0 до 1.0). Опциональный параметр.
`corner_radius`	Радиус скругления всех углов в пикселях. Опциональный параметр.
`corner_radii`	Массив из 4 значений для индивидуального скругления углов [topLeft, topRight, bottomRight, bottomLeft]. Опциональный параметр.
`backdrop_scope`	Область поиска фона для эффекта. Опциональный параметр, по умолчанию `"card"`. Доступные значения: `"card"` — поиск фона ограничивается ближайшим предком `Div2View` (текущей карточкой). Стандартное поведение. `"window"` — поиск фона расширяется на все окно приложения. Позволяет захватывать фон за пределами текущей карточки, включая соседние `Div2View` и нативные виды хоста. Требует Android 13 (API 33) и выше. На более старых версиях Android значение автоматически деградирует до `"card"`. Важно Производительность при использовании `backdrop_scope: "window"` Режим захвата всего окна требует перерисовки всего дерева представлений при каждой инвалидации эффекта, что может быть ресурсоемким. Используйте этот режим только когда необходимо захватить фон за пределами текущей карточки.
`backdrop_id`	Идентификатор конкретного view для захвата фона. Если указан вместе с `backdrop_scope: "window"`, поиск тега происходит во всем окне. Если не указан, захватывается всё содержимое окна, находящееся визуально под элементом. Опциональный параметр.

Особенности работы:

На Android 13+ (Tiramisu) используется RenderNode для оптимальной производительности
На более старых версиях Android используется Canvas для захвата фона
Расширение автоматически отслеживает изменения положения и состояния фонового view (скролл, layout, draw)
Поддерживает два варианта подсветки краев: простой (Plain) и с отражением (Reflection) для Android 13+
Эффект корректно применяется даже к элементам без явно заданного параметра background
Нераспознанное значение backdrop_scope приводит к ошибке парсинга и отключению эффекта

Интеграция на Android:

val backdropEffectHandler = BackdropEffectExtensionHandler()
val divConfiguration = DivConfiguration.Builder(imageLoader)
    .extension(backdropEffectHandler)
    .build()
val divContext = DivContext(baseContext = this, configuration = divConfiguration)

Для программной настройки эффектов используйте BackdropEffectDrawable:

val backdropDrawable = BackdropEffectDrawable()
backdropDrawable.setBlurEffect(radius = 10f)
backdropDrawable.setRefractionEffect(height = 5f, strength = 0.5f, chromaticAberration = 0.3f)
backdropDrawable.setColorAdjustment(brightness = 1.2f, contrast = 1.1f, saturation = 0.9f)
backdropDrawable.setRimHighlightEffect(angle = 45f, fade = 0.5f)
backdropDrawable.setCornerRadius(radius = 16f)
// Или для индивидуальных радиусов:
backdropDrawable.setCornerRadii(floatArrayOf(16f, 8f, 8f, 16f))

Пример использования с захватом фона за пределами карточки:

Пример с backdrop_scope: window

{
  "extensions": [
    {
      "id": "backdrop-effect",
      "params": {
        "blur_radius": 15.0,
        "backdrop_scope": "window"
      }
    }
  ]
}

Этот пример размывает весь фон окна приложения, находящийся под элементом, включая контент за пределами текущей карточки.

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

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

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

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

visibility-action

Вопросы и ответы