Свойства изображений
Ссылка на изображение
Ссылка на изображение указывается с помощью параметра 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 для изображений следует следующим принципам:
- Когда и ширина, и высота установлены на
wrap_content, изображение отображается в своих естественных размерах с учетом плотности экрана устройства - Когда один размер установлен на
wrap_content, а другой имеет фиксированный размер, размерwrap_contentрассчитывается на основе фиксированного размера и соотношения сторон изображения - Когда указано соотношение сторон, оно переопределяет естественное соотношение сторон изображения
Сценарии
Оба размера используют 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.