multiSelectComboBox 多选下拉框

基本用法

当用户点击控件时可以打开下拉列表。使用键盘的上下键或者在控件中输入内容也可以打开下拉列表。

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

数据绑定

在线示例

数据绑定是指将组件与 数据容器 进行关联。可视化组件或相应数据容器中的更改可以触发彼此的更新。有关详细信息，请参阅 使用数据组件。

如需创建关联至数据的 multiSelectComboBox，请使用 dataContainer 和 property xml 属性。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 User 实体的 InstanceContainer 容器。
2 容器内实体的内联 fetch plan。
3 Hobby 实体的 CollectionContainer 容器。
4 multiSelectComboBox 使用 hobbiesDc 作为选项容器，下拉列表中显示用户的爱好。

组件值为一组选择的条目。

使用 MetaClass

使用 multiSelectComboBox 时，还可以不直接指定关联的数据，即无需设置 dataContainer 或 property 属性。此时，需要使用 metaClass 属性指定实体类型。itemsContainer 属性指定选项实例的集合。

例如，组件可以使用 Hobby 实体，其元数据类为 Hobby。

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

通用下拉列表功能

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 属性控制所选条目在选项列表 overlay 中的显示方式。

以下是其工作原理：

  • 如果 selectedItemsOnTop 设置为 true，则已选择的条目将显示在 overlay 的顶部，其他未选择的条目将保留在底部。这种排列方式为用户提供了非常直观的展示，特别是用户需要频繁查看最近选择的条目时。

  • 如果 selectedItemsOnTop 设置为 false（默认值），则所选条目将按其选择顺序显示，而不会移动到 overlay 的顶部。这种排列保持了选择的顺序，当选择的顺序比较重要或与其他 UI 元素的视觉一致性很重要的情况下，可以首选这种排列方式。

选项获取回调

在线示例

multiSelectComboBox 可以根据用户输入批量加载选项。

例如，当用户输入 foo 时，组件会从数据库中加载最多 50 个名称中包含 foo 的选项，并在下拉列表显示。当用户向下滚动列表时，组件会获取具有相同查询语句的下一批 50 个选项，并将添加到选项列表中。

声明式配置

要实现这个功能，需要定义内部的 itemsQuery 元素。

itemsQuery 元素需要在内部的 query 元素中定义 JPQL 查询语句，以及通过几个属性配置如何加载数据：

  • escapeValueForLike - 启用搜索包含特殊符号的值：%、\ 等。默认为 false。

  • searchStringFormat - 一个包含变量占位符的字符串，该占位符在查询时将替换为实际值。

  • class（可选）- 指定需要获取实体类的全限定名称。

  • fetchPlan（可选）- 指定加载数据时需要使用的 fetch plan。

itemsQuery 元素有下列内部元素：

  • query - 定义 JPQL 查询语句的元素。

  • fetchPlan - 可选的描述符，用于定义 fetch plan。

multiSelectComboBox 中配置 itemsQuery 的示例：

<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 获取，但是也可以自定义一个 service 获取。

验证

如需检查 multiSelectComboBox 组件输入的值，可以通过内部元素 validators 使用 validator。

下面是 multiSelectComboBox 可以使用的预定义验证器：

XML 元素

validators

预定义验证器

custom - notEmpty - notNull - size

XML 属性

在 Jmix 中，所有组件都有一些作用一致的 通用属性。 下面是 multiSelectComboBox 的特殊属性：

名称

描述

默认值

autoExpand

当组件没有足够的空间展示选项的小卡片时，使用这个属性控制组件的行为。参阅 自动展开。

NONE

metaClass

为 multiSelectComboBox 定义一个元数据类。 当组件不与数据容器关联时需要设置该属性。当关联数据容器时，实体类型通过数据容器确定。参阅 使用 MetaClass。

opened

设置下拉列表是否展开。

false

selectedItemsOnTop

是否在 overlay 顶部显示已选条目的分组。参阅 已选条目置顶。

false

事件和处理器

在 Jmix 中，所有组件都有一些 通用事件和处理器，可以按相同的方法设置。 下面是 multiSelectComboBox 的特殊事件和处理器：

在 Jmix Studio 生成处理器桩代码时，可以使用 Jmix UI 组件面板的 Handlers 标签页或者视图类顶部面板的 Generate Handler 添加，也可以通过 Code → Generate 菜单（Alt+Insert / Cmd+N）生成。

名称

描述

itemLabelGenerator

com.vaadin.flow.component.ItemLabelGenerator 可以自定义某个选项展示给用户的名称。参阅 comboBox 的 itemLabelGenerator 和 在线示例。

itemsFetchCallback

仅在需要时加载选项数据。参阅 选项获取回调。

renderer

用于设置 Renderer，为列表中的每个选项自定义渲染。但这不会改变已选择选项的渲染方式，这可以通过 ItemLabelGenerator 配置。参考 在线示例。

参考

Vaadin 文档