ImageBase

Базовый компонент по работе с изображениями, лежит в основе Avatar и Image. Наследует все свойства HTML-элемента <img> и добавляет возможность накладывать различные элементы поверх изображения.

Загружается...

Задать размеры изображения можно через свойства size (если ширина и высота равны) или widthSize и heightSize (если ширина и высота отличаются).

Используйте предопределённые размеры (16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 56 | 64 | 72 | 80 | 88 | 96).

Пользовательские значения свойствам size или widthSize/heightSize задаются только числами, либо строками с указанием пикселей (33px), другие единицы измерения не допускаются дизайн-системой для сохранения возможности рассчитывать радиус скругления.

С заданным свойством keepAspectRatio можно не указывать либо ширину, либо высоту картинки - оригинальные соотношения сторон сохраняются.

Если вам необходимо растянуть изображение на всю ширину или высоту контейнера, то допускается widthSize или heightSize указать 100%.

Загружается...

Добавляйте дополнительные элементы поверх изображения:

На случай, если картинка не смогла загрузиться, будет отображаться иконка-заглушка. Размер иконки-заглушки должен зависеть от размеров изображения.

Загружается...

Индикатор в правом нижнем углу компонента:

Загружается...

Перекрывающий картинку элемент задаётся через Image.Overlay:

Загружается...

Особенность компонента заключается в способе его отображения через свойство visibility. Если оно явно не задано, то по умолчанию на устройствах с указателем (например, мышь) применяется on-hover, позволяющее показывать наложение при наведении на картинку, на остальных устройствах (например, мобильные) наложение показывается всегда.

С помощью свойства theme можно задать цвет наложения, по умолчанию наследуется тема приложения.

Позиционированный компонент расположенный поверх изображения в произвольном месте задаётся ImageBase.FloatElement:

Загружается...

Размер иконки для бейджа необходимо подстраивать под разные значения свойства size компонента. Например, для изображений размером 28x28 лучше смотрятся иконки бейджа размером 12x12. Дизайн-система уже определяет наилучшие размеры иконок, поэтому вместо ручного подбора вы можете использовать функцию getBadgeIconSizeByImageBaseSize и на её основе реализовать рендер иконки:

import { ImageBaseContext, getBadgeIconSizeByImageBaseSize } from '@vkontakte/vkui';
 
// Убедитесь, что используете контекст в компоненте или хуке, который расположен ниже `ImageBase`.
const { size } = React.useContext(ImageBaseContext);
const iconSize = getBadgeIconSizeByImageBaseSize(size);
// ИЛИ если размер изображения статичный и всегда равен одному значению
const iconSize = getFallbackIconSizeByImageBaseSize(56);
 
// Теперь используйте iconSize для выбора иконки в нужном размере

Размер иконки для наложения необходимо подстраивать под разные значения свойства size компонента. Например, для изображений размером 28x28 лучше смотрятся иконки наложения размером 20x20. Дизайн-система уже определяет наилучшие размеры иконок, поэтому вместо ручного подбора вы можете использовать функцию getOverlayIconSizeByImageBaseSize и на её основе реализовать рендер иконки:

import { ImageBaseContext, getOverlayIconSizeByImageBaseSize } from '@vkontakte/vkui';
 
// Убедитесь, что используете контекст в компоненте или хуке, который расположен ниже `ImageBase`.
const { size } = React.useContext(ImageBaseContext);
const iconSize = getOverlayIconSizeByImageBaseSize(size);
// ИЛИ если размер изображения статичный и всегда равен одному значению
const iconSize = getFallbackIconSizeByImageBaseSize(56);
 
// Теперь используйте iconSize для выбора иконки в нужном размере

Размер иконки, которая будет отрисована, если изображение не удалось загрузить, необходимо подстраивать под разные значения свойства size компонента. Например, для изображений размером 28x28 лучше смотрятся иконки размером 20x20. Дизайн-система уже определяет наилучшие размеры иконок, поэтому вместо ручного подбора вы можете использовать функцию getFallbackIconSizeByImageBaseSize и на её основе реализовать рендер иконки:

import { ImageBaseContext, getFallbackIconSizeByImageBaseSize } from '@vkontakte/vkui';
 
// Убедитесь, что используете контекст в компоненте или хуке, который расположен ниже `ImageBase`.
const { size } = React.useContext(ImageBaseContext);
const iconSize = getFallbackIconSizeByImageBaseSize(size);
// ИЛИ если размер изображения статичный и всегда равен одному значению
const iconSize = getFallbackIconSizeByImageBaseSize(56);
 
// Теперь используйте iconSize для выбора иконки в нужном размере
СвойствоОписание
elementTimingstring

Смотри https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/elementtiming ↗.

По умолчанию: -
fallbackIconReactElement<ImageBaseExpectedIconProps, string | JSXElementConstructor<any>>

Фолбек на случай, если картинка не прогрузилась.

По умолчанию: -
filterFilter

Пользовательское значения стиля filter Подробнее можно почитать в документации ↗.

По умолчанию: -
getRefRef<HTMLImageElement>
По умолчанию: -
getRootRefRef<HTMLDivElement>
По умолчанию: -
heightSizestring | number

Высота изображения.

По умолчанию: -
keepAspectRatioboolean

Флаг для сохранения пропорций картинки. Для корректной работы необходимо задать размеры хотя бы одной стороны картинки.

По умолчанию: false
noBorderboolean

Отключает обводку.

По умолчанию: false
objectFitObjectFit

Пользовательское значения стиля object-fit Подробнее можно почитать в документации ↗.

По умолчанию: cover
objectPositionObjectPosition<string | number>

Пользовательское значения стиля object-position Подробнее можно почитать в документации ↗.

По умолчанию: -
sizeLiteralUnion<16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 56 | 64 | 72 | 80 | 88 | 96, number>

Задаёт размер картинки.

Используйте размеры заданные дизайн-системой 16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 56 | 64 | 72 | 80 | 88 | 96.

По умолчанию: -
widthSizestring | number

Ширина изображения.

По умолчанию: -
withTransparentBackgroundboolean

Отключает фон, заданный по умолчанию. Полезен для отображения картинок с прозрачностью.

По умолчанию: -
СвойствоОписание
background"stroke" | "shadow"

Вид подложки под иконку.

  • "stroke" – имитирует вырез (⚠️ если фон под компонентом динамический, то ожидайте баг).
  • "shadow" – добавляет небольшую тень.
По умолчанию: shadow
childrenReactElement<ImageBaseExpectedIconProps, string | JSXElementConstructor<any>>

Принимает иконку.

По умолчанию: -
getRootRefRef<HTMLDivElement>
По умолчанию: -
СвойствоОписание
childrenReactNode | ReactElement<ImageBaseExpectedIconProps, string | JSXElementConstructor<any>>

Принимает иконку.

По умолчанию: -
classNamestring

className для компонента.

По умолчанию: -
getRootRefRef<HTMLDivElement>
По умолчанию: -
onClickMouseEventHandler<HTMLElement>

Обработчик взаимодействия с элементом. По умолчанию сам компонент является интерактивным элементом. Передав значение равное 'undefined' или не передав этот параметр вовсе, можно отключить такое поведение, что дает возможность передавать отдельные интерактивные элементы в children.

По умолчанию: -
theme"dark" | "light"

Задаёт тему оформления.

По умолчанию: -
visibility"on-hover" | "always"

Определяет каким образом должен показываться оверлей.

  • "on-hover" – на наведение указателя мыши.
  • "always" – всегда показывать.
По умолчанию: -
СвойствоОписание
blockIndentFloatElementIndentation

Отступ компонента от края контейнера по вертикали.

По умолчанию: -
getRootRefRef<HTMLDivElement>
По умолчанию: -
inlineIndentFloatElementIndentation

Отступ компонента от края контейнера по горизонтали.

По умолчанию: -
placementFloatElementPlacement

Позиция компонента относительно родителя.

По умолчанию: -
visibility"on-hover" | "always"

Режим отображения компонента:

  • "always": Всегда
  • "on-hover": При наведении на картинку.
По умолчанию: always