--- metadata: - name: generator content: Diplodoc Platform v5.50.3 alternate: - https://divkit.tech/docs/en/concepts/image.md - https://divkit.tech/docs/ru/concepts/image.md --- > **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/ru/llms.txt # Свойства изображений ## Ссылка на изображение {#image_url} Ссылка на изображение должна быть указана с помощью обязательного параметра `image_url`. Если вы хотите отобразить заглушку, и у вас нет корректной ссылки, вы можете указать значение `"image_url": "empty://"`. Для загрузки изображений из ассетов можно использовать ссылку `"image_url": "divkit-asset://image.png"`. На iOS также можно указать конкретный bundle для загрузки изображений через параметр `bundle` в query string: `"image_url": "divkit-asset://image.png?bundle=com.example.app"`. ## Поддерживаемые форматы изображений {#supported-formats} DivKit поддерживает различные форматы изображений для разных платформ: ### Основные форматы - **PNG** - растровые изображения с прозрачностью - **JPEG** - растровые изображения с сжатием - **WebP** - современный формат с лучшим сжатием - **GIF** - анимированные изображения - **SVG** - векторные изображения ### Анимированные форматы - **Animated WebP** - анимированные изображения в формате WebP - **GIF** - классические анимированные изображения ### Формат изображений SVG {#svg} DivKit поддерживает формат изображений SVG. Вы можете загружать SVG-файлы из ассетов, используя стандартный формат: - `"image_url": "divkit-asset://image.svg"` На Android также можно использовать альтернативный формат: - `"image_url": "file:///android_asset/divkit/image.svg"` ## Масштаб изображения {#image-scale} Вы можете задать масштаб изображения в параметре `scale`: - `fill` — заполняет все доступное место, что не помещается — обрезается; - `fit` — вписывается в границы, оставшееся место будет пустым; - `no_scale` — размер как есть. Внутри границ элемента расположение картинки можно менять с помощью выравнивания через `content_alignment_horizontal` и `content_alignment_vertical`. ![](../_images/create-card/scale-types-screenshot.png =200x) {% cut "Посмотреть интерактивный пример" %} {% endcut %} ## Поведение wrap_content для изображений {#wrap-content} При использовании `wrap_content` с изображениями в DivKit, компонент рассчитывает соответствующие размеры на основе естественного размера изображения и любых предоставленных ограничений. ### Основные принципы Поведение `wrap_content` для изображений следует следующим принципам: 1. Когда и ширина, и высота установлены на `wrap_content`, изображение отображается в своих естественных размерах с учетом плотности экрана устройства 2. Когда один размер установлен на `wrap_content`, а другой имеет фиксированный размер, размер `wrap_content` рассчитывается на основе фиксированного размера и соотношения сторон изображения 3. Когда указано соотношение сторон, оно переопределяет естественное соотношение сторон изображения ### Сценарии #### Оба размера используют wrap_content Когда и ширина, и высота установлены на `wrap_content`, изображение будет отображаться в своем естественном размере: ```json { "type": "image", "image_url": "https://example.com/image.png", "width": { "type": "wrap_content" }, "height": { "type": "wrap_content" } } ``` В этом случае размер div будет определяться фактическим размером изображения. #### Один размер фиксированный, другой wrap_content Когда один размер фиксирован, а другой использует `wrap_content`, размер `wrap_content` рассчитывается на основе фиксированного размера и соотношения сторон изображения: ```json { "type": "image", "image_url": "https://example.com/image.png", "width": { "type": "wrap_content" }, "height": { "type": "fixed", "value": 150 } } ``` В этом примере ширина будет рассчитана на основе фиксированной высоты (150) и соотношения сторон изображения. #### Использование соотношения сторон Когда указано соотношение сторон, оно переопределяет естественное соотношение сторон изображения: ```json { "type": "image", "image_url": "https://example.com/image.png", "width": { "type": "wrap_content" }, "height": { "type": "wrap_content" }, "aspect": { "ratio": 2 } } ``` В этом примере изображение будет поддерживать соотношение сторон 2:1 (ширина:высота), независимо от его естественного соотношения сторон. ## Динамическое изменение размеров Когда изображение с размерами `wrap_content` загружается асинхронно, макет будет пересчитан после загрузки изображения, что потенциально может вызвать смещение макета. Чтобы избежать этого, рассмотрите возможность использования фиксированных размеры или заполнителя с теми же размерами, что и ожидаемое изображение. ## Заглушки {#placeholders} До загрузки изображения отображается серая заглушка. Вы можете вставить вместо нее: - `placeholder_color` — цветную однотонную заглушку; - `preview` — картинку, закодированную в base64; - `preview_url` — ссылку на изображение-заглушку (поддерживается для GIF изображений). Если `preview` и `placeholder_color` указаны вместе, `preview` имеет приоритет при отображении. Для GIF изображений `preview_url` может использоваться как альтернатива `preview`. ![](../_images/create-card/placeholders-no-code.png =300x) {% cut "Посмотреть интерактивный пример" %} {% endcut %} ## Замена заглушки с анимацией {#animation} После завершения загрузки изображения заглушка будет заменена на скачанную картинку. Чтобы замена произошла с эффектом fade-анимации, укажите параметр `appearance_animation`: ```json translate=no { "type": "image", "appearance_animation": { "type": "fade", "alpha": 0.0, "duration": 200.0 }, "image_url": ... } ``` ## Эффекты изображений {#image-effects} DivKit поддерживает различные эффекты для изображений: ### Blur эффект (размытие) Применяет размытие к изображению. Поддерживается для форматов PNG, SVG и WebP. ### Tint эффект (тонирование) Изменяет цвет изображения с помощью тонирования. Поддерживается для форматов PNG, SVG и WebP. ### Комбинированные эффекты Можно комбинировать несколько эффектов для создания сложных визуальных результатов. ## Особенности платформ {#platform-specific} ### iOS {#ios} На iOS, для ограничения доступа к ресурсам, все изображения ассетов divkit должны начинаться с префикса 'divkit.'. Например, если вы используете `"image_url": "divkit-asset://image.png"`, изображение должно иметь имя `divkit.image.png` в main bundle вашего приложения. #### Поддержка нескольких bundle Начиная с версии 32.39.0, iOS поддерживает указание конкретного bundle для загрузки изображений через параметр `bundle` в URL: ```json { "type": "image", "image_url": "divkit-asset://image.png?bundle=com.example.app" } ``` Эта функция полезна в модульных архитектурах или при использовании нескольких bundle в приложении. На других платформах (Android, Web) параметр `bundle` игнорируется. ### Android {#android} #### Поддержка загрузчиков изображений DivKit для Android поддерживает популярные библиотеки загрузки изображений: - **Coil** - современный загрузчик изображений на Kotlin - **Glide** - традиционный загрузчик изображений Оба загрузчика поддерживают все форматы изображений и эффекты, включая анимированные WebP и GIF. ### Web {#web} #### Особенности работы с изображениями На Web-платформе DivKit автоматически обнаруживает использование GIF изображений и выводит предупреждение в консоль браузера при их использовании в компоненте `div-image`. Это связано с различиями в поведении анимаций между платформами: - GIF анимации на Web воспроизводятся автоматически - Поведение отличается от Android и iOS платформ - Для обеспечения кросс-платформенной совместимости рекомендуется учитывать эти различия при разработке #### Локальные ресурсы Для работы с локальными изображениями используйте схему `divkit-asset://`: ```json { "type": "image", "image_url": "divkit-asset://local_image.png" } ``` #### Ограничение размера изображений {#bitmap-size-limit} Для предотвращения крашей при загрузке больших изображений и GIF-файлов, DivKit автоматически ограничивает размер bitmap. Эта функция включена по умолчанию и помогает избежать проблем с памятью на устройствах. **Как работает ограничение:** - Максимальный размер bitmap определяется как максимальное разрешение экрана устройства - Изображения, превышающие этот размер, автоматически масштабируются вниз - Для SVG изображений применяется отдельный механизм ограничения - Функция поддерживается всеми популярными библиотеками загрузки изображений (Coil, Glide, Picasso) **Настройка ограничения:** Ограничение размера bitmap включено по умолчанию. Если вам нужно отключить эту функцию (например, для работы с очень большими изображениями), вы можете настроить это в реализации загрузчика изображений: ```kotlin // Пример для CoilDivImageLoader val imageLoader = CoilDivImageLoader( context = context, limitImageBitmapSizeEnabled = false // Отключить ограничение ) ``` {% note warning %} Отключение ограничения размера bitmap может привести к крашам приложения при работе с очень большими изображениями. Используйте эту настройку с осторожностью. {% endnote %} ## Анимированные изображения {#animated-images} DivKit поддерживает отображение анимированных изображений: ### Анимированный WebP Формат WebP поддерживает анимацию с лучшим сжатием по сравнению с GIF. ### GIF изображения Классический формат анимированных изображений. ### Особенности работы - Анимация воспроизводится автоматически после загрузки изображения - Поддерживается управление повторением анимации - Оптимизированная работа с памятью для больших анимаций - Поддерживается свойство `preview_url` для отображения заглушки до загрузки GIF изображения ### Использование preview_url для GIF изображений Для GIF изображений вы можете использовать свойство `preview_url` для указания ссылки на изображение-заглушку, которое будет отображаться до загрузки основного GIF: ```json { "type": "gif", "gif_url": "https://example.com/animation.gif", "preview_url": "https://example.com/preview.png" } ``` Это свойство поддерживается на всех платформах (Android, iOS, Web). ## Узнать больше {#troubleshooting} Вы можете обсуждать интересующие вас темы в сообществе пользователей DivKit в Telegram: [https://t.me/divkit_community_ru](https://t.me/divkit_community_ru). [Репозиторий DivKit](https://github.com/divkit/divkit)