Image

Компонент 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

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 Elements

Resources XML Elements