Свойства изображений

Ссылка на изображение

Ссылка на изображение должна быть указана с помощью обязательного параметра image_url. Если вы хотите отобразить заглушку, и у вас нет корректной ссылки, вы можете указать значение "image_url": "empty://".

Для загрузки изображений из ассетов можно использовать ссылку "image_url": "divkit-asset://image.png".

Поддерживаемые форматы изображений

DivKit поддерживает различные форматы изображений для разных платформ:

Основные форматы

  • PNG - растровые изображения с прозрачностью
  • JPEG - растровые изображения с сжатием
  • WebP - современный формат с лучшим сжатием
  • GIF - анимированные изображения
  • SVG - векторные изображения

Анимированные форматы

  • Animated WebP - анимированные изображения в формате WebP
  • GIF - классические анимированные изображения

Формат изображений SVG

DivKit поддерживает формат изображений SVG. Вы можете загружать SVG-файлы из ассетов, используя стандартный формат:

  • "image_url": "divkit-asset://image.svg"

На Android также можно использовать альтернативный формат:

  • "image_url": "file:///android_asset/divkit/image.svg"

Масштаб изображения

Вы можете задать масштаб изображения в параметре scale:

  • fill — заполняет все доступное место, что не помещается — обрезается;
  • fit — вписывается в границы, оставшееся место будет пустым;
  • no_scale — размер как есть.

Внутри границ элемента расположение картинки можно менять с помощью выравнивания через content_alignment_horizontal и content_alignment_vertical.

Посмотреть интерактивный пример

Поведение wrap_content для изображений

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

Основные принципы

Поведение wrap_content для изображений следует следующим принципам:

  1. Когда и ширина, и высота установлены на wrap_content, изображение отображается в своих естественных размерах с учетом плотности экрана устройства
  2. Когда один размер установлен на wrap_content, а другой имеет фиксированный размер, размер wrap_content рассчитывается на основе фиксированного размера и соотношения сторон изображения
  3. Когда указано соотношение сторон, оно переопределяет естественное соотношение сторон изображения

Сценарии

Оба размера используют wrap_content

Когда и ширина, и высота установлены на wrap_content, изображение будет отображаться в своем естественном размере:

{
  "type": "image",
  "image_url": "https://example.com/image.png",
  "width": {
    "type": "wrap_content"
  },
  "height": {
    "type": "wrap_content"
  }
}

В этом случае размер div будет определяться фактическим размером изображения.

Один размер фиксированный, другой wrap_content

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

{
  "type": "image",
  "image_url": "https://example.com/image.png",
  "width": {
    "type": "wrap_content"
  },
  "height": {
    "type": "fixed",
    "value": 150
  }
}

В этом примере ширина будет рассчитана на основе фиксированной высоты (150) и соотношения сторон изображения.

Использование соотношения сторон

Когда указано соотношение сторон, оно переопределяет естественное соотношение сторон изображения:

{
  "type": "image",
  "image_url": "https://example.com/image.png",
  "width": {
    "type": "wrap_content"
  },
  "height": {
    "type": "wrap_content"
  },
  "aspect": {
    "ratio": 2
  }
}

В этом примере изображение будет поддерживать соотношение сторон 2:1 (ширина:высота), независимо от его естественного соотношения сторон.

Динамическое изменение размеров

Когда изображение с размерами wrap_content загружается асинхронно, макет будет пересчитан после загрузки изображения, что потенциально может вызвать смещение макета. Чтобы избежать этого, рассмотрите возможность использования фиксированных размеры или заполнителя с теми же размерами, что и ожидаемое изображение.

Заглушки

До загрузки изображения отображается серая заглушка. Вы можете вставить вместо нее:

  • placeholder_color — цветную однотонную заглушку;
  • preview — картинку, закодированную в base64.

Если preview и placeholder_color указаны вместе, preview имеет приоритет при отображении.

Посмотреть интерактивный пример

Замена заглушки с анимацией

После завершения загрузки изображения заглушка будет заменена на скачанную картинку. Чтобы замена произошла с эффектом fade-анимации, укажите параметр appearance_animation:

{
    "type": "image",
    "appearance_animation": {
        "type": "fade",
        "alpha": 0.0,
        "duration": 200.0
    },
    "image_url": ...
}

Эффекты изображений

DivKit поддерживает различные эффекты для изображений:

Blur эффект (размытие)

Применяет размытие к изображению. Поддерживается для форматов PNG, SVG и WebP.

Tint эффект (тонирование)

Изменяет цвет изображения с помощью тонирования. Поддерживается для форматов PNG, SVG и WebP.

Комбинированные эффекты

Можно комбинировать несколько эффектов для создания сложных визуальных результатов.

Особенности платформ

iOS

На iOS, для ограничения доступа к ресурсам, все изображения ассетов divkit должны начинаться с префикса 'divkit.'. Например, если вы используете "image_url": "divkit-asset://image.png", изображение должно иметь имя divkit.image.png в main bundle вашего приложения.

Android

Поддержка загрузчиков изображений

DivKit для Android поддерживает популярные библиотеки загрузки изображений:

  • Coil - современный загрузчик изображений на Kotlin
  • Glide - традиционный загрузчик изображений

Оба загрузчика поддерживают все форматы изображений и эффекты, включая анимированные WebP и GIF.

Локальные ресурсы

Для работы с локальными изображениями используйте схему divkit-asset://:

{
  "type": "image",
  "image_url": "divkit-asset://local_image.png"
}

Ограничение размера изображений

Для предотвращения крашей при загрузке больших изображений и GIF-файлов, DivKit автоматически ограничивает размер bitmap. Эта функция включена по умолчанию и помогает избежать проблем с памятью на устройствах.

Как работает ограничение:

  • Максимальный размер bitmap определяется как максимальное разрешение экрана устройства
  • Изображения, превышающие этот размер, автоматически масштабируются вниз
  • Для SVG изображений применяется отдельный механизм ограничения
  • Функция поддерживается всеми популярными библиотеками загрузки изображений (Coil, Glide, Picasso)

Настройка ограничения:

Ограничение размера bitmap включено по умолчанию. Если вам нужно отключить эту функцию (например, для работы с очень большими изображениями), вы можете настроить это в реализации загрузчика изображений:

// Пример для CoilDivImageLoader
val imageLoader = CoilDivImageLoader(
    context = context,
    limitImageBitmapSizeEnabled = false // Отключить ограничение
)

Важно

Отключение ограничения размера bitmap может привести к крашам приложения при работе с очень большими изображениями. Используйте эту настройку с осторожностью.

Анимированные изображения

DivKit поддерживает отображение анимированных изображений:

Анимированный WebP

Формат WebP поддерживает анимацию с лучшим сжатием по сравнению с GIF.

GIF изображения

Классический формат анимированных изображений.

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

  • Анимация воспроизводится автоматически после загрузки изображения
  • Поддерживается управление повторением анимации
  • Оптимизированная работа с памятью для больших анимаций

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

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

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

Предыдущая
Визуальное оформление элементов
Следующая
Свойства текста