entityComboBox

entityComboBox позволяет пользователям выбирать экземпляр сущность из раскрывающегося списка и выполнять для него действия.

XML-элемент

entityComboBox

Java-класс

EntityComboBox

Быстрый старт

ДЕМО

Компонент entityComboBox обычно используют, когда значение поля должно хранить ссылку на сущность. Пользователь может выбрать экземпляр сущности и выполнить связанные с ним действия.

При нажатии на поле или кнопку со стрелкой открывается выпадающий список существующих экземпляров сущности.

Если ленивая загрузка не настроена, компонент загружает список всех доступных экземпляров в память браузера и сервера. При большом количестве элементов это расходует значительные системные ресурсы и снижает производительность. Кроме того, в длинном выпадающем списке сложно найти нужный экземпляр.

Если ожидаемое количество элементов велико, например, тысячи или больше, или если выбор требует предоставления дополнительного контекста о каждом элементе, рекомендуется использовать entityPicker.

В следующем примере entityComboBox используется для выбора отдела пользователя:

<data>
    <instance id="orderDc"
              class="io.jmix.uisamples.entity.Order">
        <fetchPlan extends="_local">
            <property name="customer" fetchPlan="_local"/>
        </fetchPlan>
    </instance>
    <collection id="customersDc"
                class="io.jmix.uisamples.entity.Customer"
                fetchPlan="_local">
        <loader id="customersDl">
            <query>
                <![CDATA[select e from Customer e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <entityComboBox dataContainer="orderDc"
                    itemsContainer="customersDc"
                    property="customer"
                    width="15em"
                    label="With actions">
        <actions>
            <action id="lookup" type="entity_lookup"/>
            <action id="clear" type="entity_clear"/>
        </actions>
    </entityComboBox>
    <entityComboBox dataContainer="orderDc"
                    itemsContainer="customersDc"
                    property="customer"
                    width="15em"
                    label="Without actions"/>
</layout>

Дополнительные интерактивные примеры использования entityComboBox и его вариантов:

entityComboBox связанный с данными

Используйте атрибуты dataContainer и property, чтобы связать entityComboBox с атрибутом сущности. Контейнер данных предоставляет экземпляр сущности, property указывает изменяемый ссылочный атрибут, а itemsContainer — доступные для выбора сущности.

Выбор сущности

Если вам просто нужно выбрать экземпляр конкретной сущности, укажите эту сущность, используя атрибут metaClass. Чтобы указать коллекцию экземпляров для выбора, используйте атрибут itemsContainer.

<entityComboBox metaClass="Department"
                itemsContainer="departmentsDc">
    // ...
</entityComboBox>

Обновление атрибута связанной сущности

Выбор экземпляра часто изменяет атрибут другого экземпляра. В приведённом выше примере выбор Department связывает экземпляр User с выбранным отделом.

В таких случаях вам нужно будет привязать компонент к контейнеру данных, содержащему экземпляр, и указать атрибут для обновления, используя атрибуты dataContainer и property соответственно. Чтобы указать коллекцию экземпляров для выбора, используйте атрибут itemsContainer.

<entityComboBox dataContainer="userDc"
                property="department"
                itemsContainer="departmentsDc">
    // ...
</entityComboBox>

Действия

ДЕМО

Изначально entityComboBox не содержит действий. Добавьте их явно, например:

<data>
    <instance id="orderDc"
              class="io.jmix.uisamples.entity.Order">
        <fetchPlan extends="_local">
            <property name="customer" fetchPlan="_local"/>
        </fetchPlan>
    </instance>
    <collection id="customersDc"
                class="io.jmix.uisamples.entity.Customer"
                fetchPlan="_local">
        <loader id="customersDl">
            <query>
                <![CDATA[select e from Customer e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <entityComboBox dataContainer="orderDc"
                    itemsContainer="customersDc"
                    property="customer"
                    width="15em"
                    label="With actions">
        <actions>
            <action id="lookup" type="entity_lookup"/>
            <action id="clear" type="entity_clear"/>
        </actions>
    </entityComboBox>
    <entityComboBox dataContainer="orderDc"
                    itemsContainer="customersDc"
                    property="customer"
                    width="15em"
                    label="Without actions"/>
</layout>

Чтобы добавить действие в Jmix Studio, выберите компонент в XML-дескрипторе экрана или в панели структуры Jmix UI и нажмите кнопку Add→Action в панели инспектора Jmix UI.

Подробную информацию об определении пользовательских и предопределённых действий смотрите в разделе Действия для entityPicker.

Ленивая загрузка

ДЕМО

Компонент может загружать элементы порциями по мере ввода, а не все сразу. Это обеспечивает быструю работу даже с большим количеством элементов.

Декларативная конфигурация

Чтобы реализовать ленивую загрузку в дескрипторе экрана, вместо указания атрибута itemsContainer, настройте вложенный элемент itemsQuery. Например, чтобы загружать не более 30 элементов и отображать их в списке, сделайте следующее:

<layout>
    <tabSheet id="tabSheet" width="100%">
        <tab id="declarativeTab" label="Declaratively">
            <entityComboBox id="declarativeEntityComboBox" label="Customer"
                            metaClass="Customer">
                <actions>
                    <action id="entityLookup" type="entity_lookup"/>
                    <action id="entityClear" type="entity_clear"/>
                </actions>
                <itemsQuery class="io.jmix.uisamples.entity.Customer"
                            searchStringFormat="(?i)%${inputString}%"
                            escapeValueForLike="true"
                            fetchPlan="_local">
                    <query>
                        <![CDATA[select e from Customer e where e.name
                        like :searchString escape '\' order by e.name asc]]>
                    </query>
                </itemsQuery>
            </entityComboBox>
        </tab>
        <tab id="programmaticTab" label="Programmatic">
            <entityComboBox id="programmaticEntityComboBox" label="Customer"
                            metaClass="Customer">
                <actions>
                    <action id="entityLookup" type="entity_lookup"/>
                    <action id="entityClear" type="entity_clear"/>
                </actions>
            </entityComboBox>
        </tab>
    </tabSheet>
</layout>

Атрибут pageSize задаёт размер порции при загрузке данных из базы. Значение по умолчанию — 50.

Атрибуты itemsQuery управляют загрузкой данных: * class – указывает полное имя класса сущностей, экземпляры которого будут выбраны. * searchStringFormat – строка, содержащая заполнитель переменной, который впоследствии заменяется фактическим значением. * escapeValueForLike – указывает, следует ли искать значения, содержащие специальные символы. По умолчанию это значение false. * fetchPlan – и необязательный дескриптор встроенного плана выборки. JPQL-запрос определяет загружаемые элементы.

itemsQuery не поддерживает использование префиксов container_ или component_ для автоматической привязки параметров к контейнерам или визуальным компонентам; такая декларативная привязка поддерживается только фасетом dataLoadCoordinator.

Программная конфигурация

Получение элементов также можно определить программно, используя обработчик itemsFetchCallback. Например:

XML
<layout>
    <tabSheet id="tabSheet" width="100%">
        <tab id="declarativeTab" label="Declaratively">
            <entityComboBox id="declarativeEntityComboBox" label="Customer"
                            metaClass="Customer">
                <actions>
                    <action id="entityLookup" type="entity_lookup"/>
                    <action id="entityClear" type="entity_clear"/>
                </actions>
                <itemsQuery class="io.jmix.uisamples.entity.Customer"
                            searchStringFormat="(?i)%${inputString}%"
                            escapeValueForLike="true"
                            fetchPlan="_local">
                    <query>
                        <![CDATA[select e from Customer e where e.name
                        like :searchString escape '\' order by e.name asc]]>
                    </query>
                </itemsQuery>
            </entityComboBox>
        </tab>
        <tab id="programmaticTab" label="Programmatic">
            <entityComboBox id="programmaticEntityComboBox" label="Customer"
                            metaClass="Customer">
                <actions>
                    <action id="entityLookup" type="entity_lookup"/>
                    <action id="entityClear" type="entity_clear"/>
                </actions>
            </entityComboBox>
        </tab>
    </tabSheet>
</layout>
Java
@Autowired
protected DataManager dataManager;

protected Collection<Customer> customers;

@Subscribe
protected void onInit(InitEvent event) {
    customers = dataManager.load(Customer.class).all().list();
}

@Install(to = "programmaticEntityComboBox", subject = "itemsFetchCallback")
protected Stream<Customer> programmaticEntityComboBoxItemsFetchCallback(Query<Customer, String> query) {
    String enteredValue = query.getFilter()
            .orElse("");

    return customers.stream()
            .filter(customer -> customer.getName() != null &&
                    customer.getName().toLowerCase().contains(enteredValue.toLowerCase()))
            .skip(query.getOffset())
            .limit(query.getLimit());
}

В этом примере данные извлекаются с использованием DataManager, но вы можете использовать этот подход для загрузки из пользовательского сервиса.

Пользовательский рендерер

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

Например, определим следующий рендерер, чтобы добавить значок перед названием отдела:

@Supply(to = "customRendererField", subject = "renderer")
private Renderer<Department> departmentRenderer() {
    return new ComponentRenderer<>(department -> {
        Icon icon = VaadinIcon.USERS.create();
        HorizontalLayout contentBox = uiComponents.create(HorizontalLayout.class);
        contentBox.setPadding(false);
        contentBox.add(icon);
        contentBox.add(department.getName());
        return contentBox;
    });
}

В качестве альтернативы вы можете отображать элементы, используя вложенный элемент fragmentRenderer. Обратитесь к разделу Рендерер фрагментов для получения дополнительной информации.

Варианты темы

Используйте атрибут themeNames, чтобы применить один или несколько вариантов темы.

Вариант Описание Поддерживается в

align-left

Выравнивает значение поля по левому краю.

Aura, Lumo

align-center

Выравнивает значение поля по центру.

Aura, Lumo

align-right

Выравнивает значение поля по правому краю.

Aura, Lumo

align-start

Выравнивает значение поля по начальной стороне с учетом текущего направления текста.

Aura

align-end

Выравнивает значение поля по конечной стороне с учетом текущего направления текста.

Aura

helper-above-field

Размещает вспомогательный текст над полем, под меткой.

Aura, Lumo

small

Уменьшает размер компонента.

Aura, Lumo

Атрибуты

entityComboBox имеет следующие уникальные атрибуты:

Имя Описание По умолчанию

allowCustomValue

Если атрибут allowCustomValue равен true, пользователь может ввести строковые значения, которые не соответствуют ни одной существующей метке элемента, что приведет к срабатыванию CustomValueSetEvent.

—

autoOpen

Определяет, открывается ли всплывающий список элементов при получении полем фокуса.

—

itemsContainer

Задаёт имя контейнера данных со списком элементов.

—

metaClass

Задаёт метакласс.

—

opened

Определяет, открыт ли выпадающий список.

—

pageSize

Задаёт размер страницы.

—

entityComboBox имеет следующие общие атрибуты:

id - alignSelf - ariaLabel - ariaLabelledBy - allowedCharPattern - autofocus - classNames - colspan - css - dataContainer - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - overlayClass - pattern - placeholder - property - readOnly - required - requiredMessage - tabIndex - themeNames - title - visible - width

Обработчики

entityComboBox имеет следующие уникальные обработчики:

Имя Описание

CustomValueSetEvent

com.vaadin.flow.component.combobox.ComboBoxBase.CustomValueSetEvent запускается, когда пользователь вводит непустое значение, которое не соответствует ни одному из существующих элементов.

itemLabelGenerator

Предоставляет текст, отображаемый для каждого элемента.

validator

Проверяет значение компонента.

renderer

Предоставляет компонент для отображения каждого элемента. See Пользовательский рендерер.

entityComboBox имеет следующие общие обработчики:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - statusChangeHandler

Элементы

Компонент entityComboBox может содержать следующие вложенные элементы: actions, fragmentRenderer, itemsQuery, prefix, tooltip, и validator.