Image - Платформа CUBA. Руководство по разработке приложений

3.5.2.1.21. Image

Компонент Image предназначен для отображения графического содержимого из различных источников. Компонент можно привязать к источнику данных или сконфигурировать программно.

XML имя компонента: image.

Компонент Image может отображать значение атрибута сущности с типом FileDescriptor или byte[]. Для этого используются атрибуты dataContainer и property, например:

<image id="image" dataContainer="employeeDс" property="avatar"/>

В данном случае компонент отображает атрибут avatar сущности Employee, находящейся в контейнере данных employeeDс.

Помимо источников данных, компонент Image может использовать в качестве источника содержимого различные типы ресурсов. Тип ресурса можно указать декларативно с помощью элементов image, перечисленных ниже:

classpath - ресурс, расположенный в classpath.

<image>
    <classpath path="com/company/sample/web/screens/myPic.jpg"/>
</image>

file - файл с изображением.

<image>
    <file path="D:\sample\modules\web\web\VAADIN\images\myImage.jpg"/>
</image>

relativePath - относительный путь к файлу в каталоге приложения.
```
<image>
    <relativePath path="VAADIN/images/myImage.jpg"/>
</image>
```

theme - ресурс из темы приложения, например: VAADIN/themes/customTheme/some/path/image.png.
```
<image>
    <theme path="com.company.sample/myPic.jpg"/>
</image>
```

url - ресурс, загружаемый по URL.

<image>
    <url url="https://www.cuba-platform.com/sites/all/themes/cuba_adaptive/img/lori.png"/>
</image>

Атрибуты image:

scaleMode - устанавливает режим масштабирования изображения. Доступны следующие режимы:
- FILL - изображение масштабируется, чтобы заполнить всю область компонента: используется вся ширина и высота компонента.
- CONTAIN - изображение подстраивается под размер компонента с сохранением пропорций, уменьшаясь или растягиваясь по меньшей стороне компонента.
- SCALE_DOWN - изображение изменяет размер, сравнивая разницу между NONE и CONTAIN, для того, чтобы найти наименьший конкретный размер объекта.
- NONE - изображение сохранит свой исходный размер, размер компонента будет равен размеру изображения.

alternateText - устанавливает альтернативный текст на случай, если ресурс недоступен или не задан.
```
<image id="image" alternateText="logo"/>
```

Параметры ресурсов image:

bufferSize - размер буфера, используемого для загрузки этого ресурса, в байтах.
```
<image>
    <file bufferSize="1024" path="C:/img.png"/>
</image>
```

cacheTime - время хранения объекта в кэше в миллисекундах.
```
<image>
    <file cacheTime="2400" path="C:/img.png"/>
</image>
```

mimeType - MIME-тип ресурса.

<image>
    <url url="https://avatars3.githubusercontent.com/u/17548514?v=4&#38;s=200"
         mimeType="image/png"/>
</image>

Для программного управления компонентом Image следует использовать следующие методы:

setValueSource() - устанавливает для изображения контейнер данных и его атрибут. Поддерживаются только атрибуты типов FileDescriptor и byte[].

Программное указание контейнера данных позволяет, к примеру, отображать изображения в ячейках таблицы:
```
frameworksTable.addGeneratedColumn("image", entity -> {
    Image image = uiComponents.create(Image.NAME);
    image.setValueSource(new ContainerValueSource<>(frameworksTable.getInstanceContainer(entity), "image"));
    image.setHeight("100px");
    return image;
});
```

setSource() - устанавливает источник изображения. Метод принимает тип ресурса и возвращает объект ресурса, который может быть сконфигурирован далее. Для каждого типа ресурсов есть свои методы, например, setPath() для ThemeResource или setStreamSupplier() для StreamResource:
Image image = uiComponents.create(Image.NAME); image.setSource(ThemeResource.class) .setPath("images/image.png");
или
image.setSource(StreamResource.class) .setStreamSupplier(() -> new FileDataProvider(fileDescriptor).provide()) .setBufferSize(1024);
Можно использовать следующие типы ресурсов, реализующие интерфейс Resource, или расширить их:
- ClasspathResource - для изображений, хранимых в classpath. Этот ресурс также можно использовать декларативно с помощью элемента classpath компонента image.
- FileDescriptorResource - для изображений, получаемых из FileStorage.
- FileResource - для изображений, хранимых в файловой системе. Этот ресурс также можно использовать декларативно с помощью элемента file компонента image.
- RelativePathResource - для изображений, хранимых в каталоге приложения. Этот ресурс также можно использовать декларативно с помощью элемента relativePath компонента image.
- StreamResource - для изображений, получаемых из потока.
- ThemeResource - для изображений темы, например, VAADIN/themes/yourtheme/some/path/image.png. Этот ресурс также можно использовать декларативно с помощью элемента theme компонента image.
- UrlResource - для изображений, загружаемых по указанному URL. Этот ресурс также можно использовать декларативно с помощью элемента url компонента image.

createResource() - создаёт ресурс изображения указанного типа. Созданный объект может быть позже передан в метод setSource().
FileDescriptorResource resource = image.createResource(FileDescriptorResource.class) .setFileDescriptor(avatar); image.setSource(resource);

addClickListener() - добавляет слушатель для отслеживания кликов по области изображения.

image.addClickListener(clickEvent -> {
    if (clickEvent.isDoubleClick())
        notifications.create()
                .withCaption("Double clicked")
                .show();
});

addSourceChangeListener() - добавляет слушатель для отслеживания изменений источника изображения.

Атрибуты image: align - alternateText - caption - captionAsHtml - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - datasource - description - descriptionAsHtml - editable - enable - box.expandRatio - height - icon - id - property - required - requiredMessage - responsive - rowspan - scaleMode - stylename - stylename - visible - width
Атрибуты ресурсов image: bufferSize - cacheTime - mimeType
Элементы image: classpath - file - relativePath - theme - url
API: addClickListener - addSourceChangeListener - createResource - setScaleMode - setSource - setValueSource