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

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

Ссылка на изображение указывается с помощью параметра image_url. Этот параметр является опциональным — вы можете не указывать URL, если хотите отобразить только заглушку или превью.

Если вы хотите отобразить заглушку без загрузки основного изображения, вы можете не указывать image_url и использовать только параметры placeholder_color или preview.

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

На iOS также можно указать конкретный bundle для загрузки изображений через параметр bundle в query string: "image_url": "divkit-asset://image.png?bundle=com.example.app".

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

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 — размер как есть;
  • stretch — растягивается до размеров элемента без сохранения пропорций.

Внутри границ элемента расположение картинки можно менять с помощью выравнивания через 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_url — ссылку на изображение-заглушку (поддерживается для GIF изображений).

Если preview и placeholder_color указаны вместе, preview имеет приоритет при отображении. Для GIF изображений preview_url может использоваться как альтернатива preview.

Изображение без URL

Изображение можно создать без указания image_url или gif_url. В этом случае будет отображаться только заглушка или превью:

{
  "type": "image",
  "width": {
    "type": "fixed",
    "value": 100
  },
  "height": {
    "type": "fixed",
    "value": 100
  },
  "placeholder_color": "#FFCCCCCC"
}

Этот подход полезен, когда нужно зарезервировать место под изображение, которое будет загружено позже, или когда изображение не требуется, но нужна визуальная заглушка.

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

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

После завершения загрузки изображения заглушка будет заменена на скачанную картинку. Чтобы замена произошла с эффектом 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.

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

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

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

Подключение загрузчиков изображений и ограничение размера bitmap на Android, а также загрузка изображений из bundle на iOS описаны на странице Ресурсы: шрифты, изображения и видео.

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

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

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

Схема divkit-asset:// поддерживается на Android и iOS. На iOS в ссылке можно указать bundle, из которого загружается изображение, см. Ресурсы.

Web

На Web-платформе DivKit автоматически обнаруживает использование GIF изображений и выводит предупреждение в консоль браузера при их использовании в компоненте div-image. Это связано с различиями в поведении анимаций между платформами:

  • GIF анимации на Web воспроизводятся автоматически
  • Поведение отличается от Android и iOS платформ
  • Для обеспечения кросс-платформенной совместимости рекомендуется учитывать эти различия при разработке

Предварительная загрузка изображений

Свойство preload_required (в Kotlin DSL — preloadRequired) устарело и будет удалено в следующей мажорной версии DivKit. Не используйте его в новых шаблонах.

Важно

Свойство preload_required устарело. Оно поддерживается для обратной совместимости, но не рекомендуется к использованию и будет удалено в следующей мажорной версии DivKit.

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

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

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

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

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

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

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

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

Использование preview_url для GIF изображений

Для GIF изображений вы можете использовать свойство preview_url для указания ссылки на изображение-заглушку, которое будет отображаться до загрузки основного GIF:

{
  "type": "gif",
  "gif_url": "https://example.com/animation.gif",
  "preview_url": "https://example.com/preview.png"
}

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

Также вы можете создать GIF-изображение без указания gif_url, используя только превью:

{
  "type": "gif",
  "width": {
    "type": "fixed",
    "value": 150
  },
  "height": {
    "type": "fixed",
    "value": 150
  },
  "preview_url": "https://example.com/preview.png"
}

Примечание

Обратная совместимость

Изображения без URL (image_url или gif_url) корректно отображаются только в актуальных версиях клиентов DivKit: старые версии такие изображения игнорируют.

Для обеспечения обратной совместимости рекомендуется:

  • Сохранять поля image_url / gif_url в ответах бэкенда даже если они не используются
  • Использовать валидный URL-заглушку (например, "empty://") для старых клиентов
  • Постепенно внедрять новую функциональность, проверяя версию клиента

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

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

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

Следующая