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

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

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

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

Формат изображений 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": ...
}

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

iOS

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

Android

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

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

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

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

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

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

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

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

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

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