Image

LIVE DEMO

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

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

Основы

Компонент Image может отображать значение атрибута сущности с типом FileRef или byte[]. В приведенном ниже примере сущность имеет атрибут image, который является ссылкой на файл в файловом хранилище:

@JmixEntity
@Table(name = "UIEX1_PERSON")
@Entity(name = "uiex1_Person")
public class Person {

    /* other attributes */

    @Column(name = "IMAGE", length = 1024)
    private FileRef image;

В простейшем случае, компонент можно связать с данными с помощью XML-атрибутов dataContainer и property:

<data readOnly="true">
    <instance id="personDc"
              class="ui.ex1.entity.Person">
        <fetchPlan extends="_base"/>
        <loader/>
    </instance>
</data>
<layout spacing="true">
    <image id="fileRefImage"
           dataContainer="personDc"
           property="image"/>
</layout>

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

Ресурсы

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

ClasspathResource

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

  • В XML: элемент classpath с атрибутом path.

    Например, если изображение находится в ui/ex1/screen/component/image/jmix-logo.png под src/main/resources, отображаемый ресурс можно указать следующим образом:

    <image scaleMode="SCALE_DOWN"
       width="20%"
       height="20%">
    <resource>
        <classpath path="ui/ex1/screen/component/image/jmix-logo.png"/>
    </resource>
</image>

  • На Java: интерфейс ClasspathResource.

    image.setSource(ClasspathResource.class)
        .setPath("ui/ex1/screen/component/image/jmix-logo.png");

FileResource

Ресурс, хранимый в файловой системе сервера.

  • В XML: элемент file с атрибутом path.

    <image scaleMode="SCALE_DOWN"
       width="20%"
       height="20%">
    <resource>
        <file path="D:\JMIX\jmix-logo.png"/>
    </resource>
</image>

  • На Java: интерфейс FileResource.

    image.setSource(FileResource.class)
        .setFile(file);

FileStorageResource

Изображение, находящееся в хранилище файлов.

  • В XML: атрибут property у image.

    <image id="fileRefImage"
       dataContainer="personDc"
       property="image"/>

  • В Java: интерфейс FileStorageResource.

    image.setSource(FileStorageResource.class)
        .setFileReference(person.getImage());

RelativePathResource

Изображение, статически обслуживаемое приложением.

По умолчанию статическое содержимое передается из каталогов classpath /static, /public, /resources, или /META-INF/resources (подробности см. в документации Spring Boot).

  • В XML: элемент relativePath с атрибутом path.

    Например, изображение, расположенное по адресу src/main/resources/static/images/jmix-icon-login.svg, может отображаться следующим образом:

    <image>
    <resource>
        <relativePath path="images/jmix-icon-login.svg"/>
    </resource>
</image>

    Изображение также будет доступно по адресу http://{host}:{port}/images/jmix-icon-login.svg.

  • В Java: интерфейс RelativePathResource.

    image.setSource(RelativePathResource.class)
        .setPath("images/jmix-icon-login.svg");

StreamResource

Изображение, предоставленное в InputStream.

  • В Java: интерфейс StreamResource.

    byte[] picture;
// picture = ...
image.setSource(StreamResource.class)
        .setStreamSupplier(() -> new ByteArrayInputStream(picture));

ThemeResource

Изображение, расположенное в текущей теме.

В приведенном ниже примере изображение находится в каталоге images нестандартной темы helium-ext:

images theme resources

Затем его можно использовать в компоненте Image следующим образом:

  • В XML: элемент theme с атрибутом path.

    <image>
    <resource>
        <theme path="images/jmix-icon-login.svg"/>
    </resource>
</image>

  • В Java: интерфейс ThemeResource:

    image.setSource(ThemeResource.class)
        .setPath("images/jmix-icon-login.svg");

UrlResource

Изображение, которое может быть загружено с произвольного URL-адреса.

  • В XML: элемент url с атрибутом url.

    <image scaleMode="SCALE_DOWN"
       width="20%"
       height="20%">
    <resource>
        <url url="https://www.jmix.io/uploads/framework_image_9efadbc372.svg"/>
    </resource>
</image>

  • В Java: интерфейс UrlResource.

    try {
    image.setSource(UrlResource.class)
            .setUrl(new URL("https://www.jmix.io/images/jmix-logo.svg"));
} catch (MalformedURLException e) {
    log.error("Invalid URL format", e);
}

Настройки ресурсов

  • bufferSize - размер буфера, используемого для загрузки этого ресурса, в байтах.

  • cacheTime - время хранения объекта в кэше в миллисекундах.

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

Например:

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

Атрибуты

  • alternateText - устанавливает альтернативный текст на случай, если ресурс недоступен или не задан.

  • scaleMode - устанавливает режим масштабирования изображения (соответствует CSS-свойству object-fit). Доступны следующие режимы:

    • FILL - изображение масштабируется, чтобы заполнить всю область компонента: используется вся ширина и высота компонента.

    • CONTAIN - изображение подстраивается под размер компонента с сохранением пропорций, уменьшаясь или растягиваясь по меньшей стороне компонента.

    • COVER - изображение масштабируется так, чтобы заполнить всю область компонента, сохраняя при этом соотношения сторон. Если пропорции изображения не совпадают с пропорциями компонента, то изображение будет обрезано по размеру.

    • SCALE_DOWN - для изображения применяется либо режим NONE, либо CONTAIN, в зависимости от того, какой режим дает меньший размер.

    • NONE - изображение сохранит свой исходный размер.

Методы

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

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

    Программное указание контейнера данных позволяет, к примеру, отображать изображения в ячейках таблицы:

    <data readOnly="true">
    <collection id="personsDc"
                class="ui.ex1.entity.Person">
        <fetchPlan extends="_base"/>
        <loader id="personsDl">
            <query>
                <![CDATA[select e from uiex1_Person e]]>
            </query>
        </loader>
    </collection>
</data>
<layout spacing="true">
    <groupTable id="personsTable"
                width="100%"
                dataContainer="personsDc">
        <columns>
            <column id="name"/>
        </columns>
    </groupTable>
</layout>
    @Autowired
private GroupTable<Person> personsTable;
@Autowired
private UiComponents uiComponents;

@Subscribe
public void onInit(InitEvent event) {
    personsTable.addGeneratedColumn("image", entity -> {
        Image<FileRef> image = uiComponents.create(Image.NAME);
        image.setValueSource(
                new ContainerValueSource<>(
                        personsTable.getInstanceContainer(entity),
                        "image"));
        image.setHeight("100px");
        image.setScaleMode(Image.ScaleMode.CONTAIN);
        return image;
    });
}

  • setSource() - устанавливает ресурс изображения. Метод принимает тип ресурса и возвращает объект ресурса, который может быть сконфигурирован далее.

    <layout spacing="true">
    <image id="programmaticImage"/>
</layout>
    @Autowired
private Image<FileRef> programmaticImage;

@Subscribe
public void onInit(InitEvent event) {
    try {
        URL url = new URL("https://www.jmix.io/images/jmix-logo.svg");
        programmaticImage.setSource(UrlResource.class).setUrl(url);
    } catch (MalformedURLException e) {
        log.error("Error", e);
    }
}

События и слушатели

Чтобы сгенерировать заглушку слушателя в Jmix Studio, выберите компонент в XML-дескрипторе экрана или на панели иерархии Jmix UI и используйте вкладку Handlers на панели инспектора Jmix UI.

В качестве альтернативы вы можете воспользоваться кнопкой Generate Handler на верхней панели контроллера экрана.

ClickEvent

См. ClickEvent.

ContextHelpIconClickEvent

См. ContextHelpIconClickEvent.

SourceChangeEvent

SourceChangeEvent отправляется при изменении источника изображения и имеет следующие методы:

  • getNewSource()

  • getOldSource()

@Subscribe("image")
public void onImageSourceChange(ResourceView.SourceChangeEvent event) {
    notifications.create()
            .withCaption("Old source was: " + event.getOldSource() +
                    "; new source is: " + event.getNewSource());
}

Чтобы создать слушателя события программно, используйте метод компонента addSourceChangeListener().

Все XML-атрибуты

Просматривать и редактировать атрибуты, применимые к компоненту, можно с помощью панели инспектора Jmix UI в конструкторе экранов Studio.

Image XML Attributes

align - alternateText - box.expandRatio - caption - captionAsHtml - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - height - htmlSanitizerEnabled - icon - id - property - required - requiredMessage - property - required - requiredMessage - rowspan - scaleMode - stylename - visible - width

Image XML Elements

resource

Resources XML Elements

classpath - file - relativePath - theme - url