entityPicker

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

XML-элемент

entityPicker

Java-класс

EntityPicker

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

ДЕМО

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

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

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

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

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

Для корректной работы примера убедитесь, что определили экран списка для сущности Department. 
<data>
    <instance id="orderDc"
              class="io.jmix.uisamples.entity.Order">
        <fetchPlan extends="_local">
            <property name="customer" fetchPlan="_local"/>
        </fetchPlan>
    </instance>
</data>
<layout>
    <entityPicker dataContainer="orderDc"
                  property="customer"
                  placeholder="Choose a customer"
                  width="15em">
        <actions>
            <action id="lookup" type="entity_lookup"/>
            <action id="clear" type="entity_clear"/>
        </actions>
    </entityPicker>
</layout>

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

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

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

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

Если вам просто нужен способ выбора экземпляра определённой сущности, укажите эту сущность, используя атрибут metaClass:

<entityPicker metaClass="Department">
    //...
</entityPicker>

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

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

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

<entityPicker dataContainer="userDc" property="department">
    //...
</entityPicker>

Действия

Вы можете определить пользовательские и предопределённые действия для entityPicker, отображаемые в виде кнопок справа. Это можно сделать либо в XML-дескрипторе, используя вложенный элемент actions, либо программно в контроллере, используя метод addAction().

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

Предопределенные действия

Когда Studio генерирует entityPicker на экране деталей, он также генерирует два предопределённых стандартных действия: entity_lookup и entity_clear. Существуют также действия entity_open и entity_openComposition.

Используйте атрибуты type и id для объявления предопределённого действия в XML.

Если вы создаёте entityPicker без действий, загрузчик XML определит только действия entity_lookup и entity_clear. Чтобы добавить другое предопределённое действие, например, entity_open, необходимо указать элемент actions следующим образом:

<entityPicker dataContainer="userDc"
              property="department"
              label="Department" >
    <actions>
        <action id="entityLookup" type="entity_lookup"/>
        <action id="entityClear" type="entity_clear"/>
        <action id="entityOpen" type="entity_open"/>
    </actions>
</entityPicker>

Элемент actions не расширяет, а переопределяет набор стандартных действий. Вам следует явно определить идентификаторы всех необходимых действий.

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

Чтобы определить пользовательское действие в XML, используйте вложенный элемент actions. Укажите атрибуты id и icon для действия:

<entityPicker id="departmentEntityPicker"
              dataContainer="userWithDeptManagerDc"
              property="department">
    <actions>
        <action id="entityLookup" type="entity_lookup"/>
        <action id="knowManager" icon="QUESTION"
                description="Know HR-manager"/>
    </actions>
</entityPicker>

Затем реализуйте пользовательскую логику в контроллере экрана, подписавшись на ActionPerformedEvent:

@ViewComponent
private EntityPicker<Department> departmentEntityPicker;

@Autowired
private Notifications notifications;

@Subscribe("departmentEntityPicker.knowManager")
public void onKnowManager(ActionPerformedEvent event) {
    Department department = departmentEntityPicker.getValue();
    if (department != null)
        notifications.create(department.getName() + " has "
                + department.getHrManager() + " HR-manager")
                .show();
    else notifications.create("Choose a department").show();
}

Вы можете сгенерировать заглушку обработчика ActionPerformedEvent с помощью Jmix Studio.

Добавление действий программно

Используйте метод addAction() для установки действий программно.

  • Добавление стандартного действия

    Например, если компонент определен в XML-дескрипторе без вложенного элемента actions, достаточно добавить недостающие стандартные действия:

    @ViewComponent
private EntityPicker<Department> departmentEntityPicker;

@Autowired
private Actions actions;

@Subscribe
public void onInit(InitEvent event) {
    departmentEntityPicker.addAction(actions.create(EntityOpenAction.ID));
}

  • Добавление пользовательского действия

    Пример создания пользовательского действия:

    @ViewComponent
private EntityPicker<Department> departmentEntityPicker;

@Subscribe
public void onInit(InitEvent event) {
    departmentEntityPicker.addAction(new BaseAction("showManager")
            .withIcon(VaadinIcon.QUESTION_CIRCLE.create())
            .withHandler(e -> {
                Department department = departmentEntityPicker.getValue();
                if (department != null)
                    notifications.create(department.getName() + " has "
                                    + department.getHrManager() + " HR-manager")
                            .show();
                else notifications.create("Choose a department").show();
            }));
}

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

Используйте атрибут 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

Атрибуты

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

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

allowCustomValue

Определяет, могут ли пользователи вводить значения, отсутствующие среди доступных элементов.

—

metaClass

Вы можете использовать entityPicker без привязки к контейнеру данных, то есть без установки dataContainer и property.

—

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

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

Обработчики

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

Имя Описание

CustomValueSetEvent

Возникает, когда пользователь вводит в поле пользовательское значение.

formatter

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

validator

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

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

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - statusChangeHandler

Элементы

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