multiSelectComboBox

ДЕМО

multiSelectComboBox позволяет пользователям выбирать один или несколько элементов из выпадающего списка. Этот компонент похож на comboBox.

XML-элемент

multiSelectComboBox

Java-класс

JmixMultiSelectComboBox

Атрибуты

id - alignSelf - allowCustomValue - allowedCharPattern - ariaLabel - ariaLabelledBy autoExpand - autoOpen - autofocus - classNames - clearButtonVisible - colspan - css - dataContainer - enabled - errorMessage - focusShortcut - height - helperText - itemsContainer itemsEnum - label - maxHeight - maxWidth - metaClass - minHeight - minWidth - opened - overlayClass - pageSize - placeholder - property - readOnly - required - requiredMessage - selectedItemsOnTop - tabIndex - themeNames - title - visible - width

Обработчики

AttachEvent - BlurEvent - ClientValidatedEvent - ComponentValueChangeEvent - CustomValueSetEvent - DetachEvent - FocusEvent - TypedValueChangeEvent - itemLabelGenerator - itemsFetchCallback - renderer - validator

Элементы

fragmentRenderer - itemsQuery - tooltip - validator

Основы

Выпадающий список открывается, когда пользователь щелкает по полю с помощью мыши. Использование клавиш Up и Down или ввод символа при фокусе на поле также открывает выпадающий список.

multi select combo box basics 
<multiSelectComboBox itemsEnum="com.company.onboarding.entity.DayOfWeek"
                     label="Day of week"/>

Привязка данных

ДЕМО

Привязка данных означает связывание визуального компонента с контейнером данных. Изменения в визуальном компоненте или соответствующем контейнере данных могут вызывать обновления друг друга. Смотрите Использование компонентов данных для получения дополнительной информации.

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

<data>
    <instance class="com.company.onboarding.entity.User" id="userDc"> (1)
        <fetchPlan extends="_base"> (2)
            <property name="hobbies" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="userDl"/>
    </instance>
    <collection class="com.company.onboarding.entity.Hobby" id="hobbiesDc"> (3)
        <fetchPlan extends="_base"/>
        <loader id="hobbiesDl">
            <query>
                <![CDATA[select e from Hobby e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <multiSelectComboBox dataContainer="userDc"
                         property="hobbies"
                         label="Hobbies"
                         itemsContainer="hobbiesDc"/> (4)
</layout>
1 InstanceContainer для сущности User.
2 Встроенный план выборки экземпляра сущности, находящегося в контейнере.
3 CollectionContainer для сущности Hobby.
4 multiSelectComboBox получает hobbiesDc в качестве контейнера элементов, чтобы в выпадающем списке отображался список хобби.

Значение компонента возвращает список выбранных элементов.

MultiSelectComboBox c MetaClass

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

Например, компонент может работать с сущностью Hobby, которая имеет имя класса метаданных Hobby.

<multiSelectComboBox metaClass="Hobby"
                     itemsContainer="hobbiesDc"/>

Общие функции comboBox

multiSelectComboBox поддерживает следующие функции из обычного comboBox:

Автоматическое расширение

Вы можете настроить multiSelectComboBox для автоматического увеличения ширины, чтобы вместить теги, представляющие выбранные элементы. Расширение работает только с неопределенным размером в нужном направлении (например, установка max-width ограничивает ширину компонента). Возможные значения:

  • VERTICAL - поле расширяется вертикально, и теги переносятся на следующую строку.

    auto expand vertical

  • HORIZONTAL - поле расширяется горизонтально, пока не достигнет максимальной ширины (max-width), затем сворачивается, чтобы отобразить переполняющий тег.

    auto expand horizontal

  • BOTH - поле расширяется горизонтально, пока не достигнет максимальной ширины (max-width), затем расширяется вертикально, и теги переносятся на следующую строку.

    auto expand both

  • NONE - поле не расширяется и сворачивается, чтобы отобразить переполняющий тег.

    auto expand none

Отображение выбранных элементов

Атрибут selectedItemsOnTop управляет способом отображения выбранных элементов в выпадающем списке.

Как это работает:

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

  • Если selectedItemsOnTop установлен в false (значение по умолчанию), выбранные элементы отображаются в том порядке, в котором они были выбраны, без перемещения в верхнюю часть выпадающего списка. Такое расположение сохраняет порядок выбора и может быть предпочтительным в сценариях, где порядок имеет решающее значение, или если важна визуальная согласованность с другими элементами интерфейса.

Получение элементов списка

ДЕМО

multiSelectComboBox может загружать элементы по частям в ответ на действия пользователя.

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

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

Для реализации этого поведения определите вложенный элемент itemsQuery.

Элемент itemsQuery должен содержать текст запроса JPQL во вложенном элементе query и несколько дополнительных атрибутов, определяющих, что и как загружать данные:

  • escapeValueForLike - включает поиск значений, содержащих специальные символы: %, \, и так далее. Значение по умолчанию - false.

  • searchStringFormat - строка Groovy. C её помощью вы можете использовать любые допустимые строковые выражения Groovy.

  • class (необязательный) - указывает полное имя класса сущности, экземпляры которой будут получены.

  • fetchPlan - необязательный атрибут, указывающий план выборки, который будет использоваться для загрузки запрошенной сущности.

Элемент itemsQuery содержит следующие вложенные элементы:

  • query - элемент, содержащий запрос JPQL.

  • fetchPlan - необязательный элемент, указывающий встроенный план выборки.

Пример использования itemsQuery в multiSelectComboBox:

<multiSelectComboBox metaClass="Hobby"
                     label="Hobby"
                     pageSize="30"> (1)
    <itemsQuery class="com.company.onboarding.entity.Hobby"
                escapeValueForLike="true"
                searchStringFormat="(?i)%${inputString}%">
        <fetchPlan extends="_base"/>
        <query>
            <![CDATA[select e from Hobby e where e.name
            like :searchString escape '\' order by e.name]]>
        </query>
    </itemsQuery>
</multiSelectComboBox>
1 Атрибут pageSize определяет размер пакета при загрузке данных из базы данных. По умолчанию он равен 50.

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

Извлечение элементов также может быть определено программно с помощью обработчика itemsFetchCallback. Например:

@Autowired
protected DataManager dataManager;

protected Collection<Hobby> hobbies;

@Subscribe
public void onInit(final InitEvent event) {
    hobbies = dataManager.load(Hobby.class).all().list();
}

@Install(to = "hobbiesComboBox", subject = "itemsFetchCallback")
private Stream<Hobby> hobbiesComboBoxItemsFetchCallback(final Query<Hobby, String> query) {
    String enteredValue = query.getFilter()
            .orElse("");

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

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

Валидация

Чтобы проверить значения, введенные в компонент multiSelectComboBox, вы можете использовать валидатор в элементе validators.

Доступны следующие предопределенные валидаторы для multiSelectComboBox:

XML-элемент

validators

Предопределенные валидаторы

custom - notEmpty - notNull - size

Атрибуты

В Jmix есть множество общих атрибутов, которые выполняют одну и ту же функцию для всех компонентов.

Ниже приведены атрибуты, специфичные для multiSelectComboBox:

Название

Описание

Значение по умолчанию

autoExpand

Управляет поведением компонента, когда недостаточно места для отображения всех выбранных элементов в виде тегов в пределах текущей ширины поля. Смотрите Автоматическое расширение.

NONE

metaClass

Определяет класс сущности для multiSelectComboBox. Задайте этот атрибут, если компонент не связан с контейнером данных. В противном случае тип сущности определяется контейнером данных. Смотрите MultiSelectComboBox c MetaClass.

opened

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

false

selectedItemsOnTop

Включает или отключает группировку выбранных элементов в верхней части выпадающего списка. Смотрите Отображение выбранных элементов.

false

Обработчики

В Jmix существует множество общих обработчиков, которые конфигурируются одинаково для всех компонентов.

Ниже приведены обработчики, специфичные для multiSelectComboBox.

Чтобы сгенерировать заглушку обработчика в Jmix Studio, используйте вкладку Handlers панели инспектора Jmix UI, или команду Generate Handler, доступную на верхней панели контроллера экрана и через меню Code → Generate (Alt+Insert / Cmd+N).

Название

Описание

itemLabelGenerator

com.vaadin.flow.component.ItemLabelGenerator можно использовать для настройки строки, отображаемой пользователю для элемента. Смотрите itemLabelGenerator для comboBox и демонстрацию.

itemsFetchCallback

Этот обработчик извлекает данные только по мере необходимости. Смотрите Получение элементов списка.

renderer

Устанавливает Renderer, ответственный за отрисовку отдельных элементов в списке возможных вариантов multiSelectComboBox. Это не влияет на то, как отображается выбранный элемент - это можно настроить с помощью ItemLabelGenerator. Смотрите демонстрацию.

Смотрите также

Смотрите документацию Vaadin для получения дополнительной информации.