entityComboBox 实体下拉框

entityComboBox 支持用户从一个下拉列表中选择单一 实体 实例，并支持用户单击右侧按钮执行特定操作。

事实上，entityComboBox 是 comboBox 和 entityPicker 的组合。

  • XML 元素：entityComboBox

  • Java 类：EntityComboBox

基本用法

满足下列情况可以使用 entityComboBox：

  • 字段值是实体实例。

  • 用户需要选择单一选项。

  • 选项列表应该比较紧凑。如果选项列表对于 radioButtonGroup 或 listBox 太长时，用下拉列表更方便。

  • 用户需要过滤功能。

  • 用户需要对关联的实体实例做一些操作。

entityComboBox 是一个带有实体实例滚动列表的文本控件。支持自定义和预定义的操作：

entity combobox basics

如需创建连接至数据的 entityComboBox，可以用 XML 的 dataContainer 和 property 属性。而 itemsContainer 属性用来创建选项列表：

<data>
    <instance class="com.company.onboarding.entity.User"
              id="userDc"> (1)
        <fetchPlan extends="_base"> (2)
            <property name="department" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="userDl"/>
    </instance>
    <collection class="com.company.onboarding.entity.Department"
                id="departmentsDc"> (3)
        <fetchPlan extends="_base"/>
        <loader id="departmentsDl">
            <query>
                <![CDATA[select e from Department e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <entityComboBox dataContainer="userDc"
                    property="department"
                    itemsContainer="departmentsDc"> (4)
        <actions>
            <action id="entityClear" type="entity_clear"/>
            <action id="entityLookup" type="entity_lookup"/>
        </actions>
    </entityComboBox>
</layout>
1 InstanceContainer - User 主实体。
2 数据容器内实体的 fetch plan。
3 CollectionContainer - Department 实体列表容器。
4 entityComboBox 将 departmentsDc 作为选项容器，展示部门列表。

如果选项数量很大（数千个或更多），请不要使用 entityComboBox。entityComboBox 会将全部选项列表加载到用户的浏览器和服务器内存中。如需从大量选项列表中进行选择，请使用 EntityPicker。

操作

entityComboBox 没有默认操作，需要显式地添加需要的操作，示例：

<entityComboBox dataContainer="userDc"
                property="department"
                itemsContainer="departmentsDc">
    <actions>
        <action id="entityClear" type="entity_clear"/>
        <action id="entityLookup" type="entity_lookup"/>
        <action id="entityOpen" type="entity_open"/>
    </actions>
</entityComboBox>

如需在 Jmix Studio 中添加 action，可以在视图 XML 或者 Jmix UI 层级结构面板中选择组件，然后在组件面板点击 Add→Action 按钮。

自定义和预定义操作的详细信息请参阅 entityPicker 的 操作 部分。

自定义过滤

entityComboBox 的过滤特性默认配置为仅展示包含输入内容的选项。同时也支持自定义过滤，例如，如果想展示以用户输入内容开头的选项：

@ViewComponent
private CollectionContainer<Department> departmentsDc;

@ViewComponent
private EntityComboBox<Department> filterEntityComboBox;

@Subscribe
public void onInit(InitEvent event) {
    ComboBox.ItemFilter<Department> filter = (department, filterString) -> department
            .getName().toLowerCase().startsWith(filterString.toLowerCase());
    filterEntityComboBox.setItems(departmentsDc,filter);
}

XML 属性

id - allowCustomValue - autoOpen - autofocus - classNames - colspan - dataContainer - enabled - errorMessage - height - helperText - invalid - itemsContainer - label - maxHeight - maxWidth - metaClass - minHeight - minWidth - opened - pattern - placeholder - preventInvalidInput - property - readOnly - required - requiredIndicatorVisible - requiredMessage - tabIndex - themeNames - title - visible - width

allowCustomValue

Vaadin

如果 allowCustomValue 属性为 true，用户可以输入不匹配任何选项的字符串值，此时会触发 CustomValueSetEvent。

注意，entityComboBox 不会自动处理自定义字符串。请使用 CustomValueSetEvent 进行处理。

默认值为 false。

itemsContainer

设置包含选项列表的数据容器名称。组件将实体的 实例名 作为选项展示。

opened

设置下拉列表是否默认打开。

默认值为 false。

事件和处理器

AttachEvent - BlurEvent - ComponentValueChangeEvent - CustomValueSetEvent - DetachEvent - FocusEvent - itemLabelGenerator - statusChangeHandler - validator

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

CustomValueSetEvent

当用户输入非空值，且不匹配任何已有选项时，发出 com.vaadin.flow.component.combobox.ComboBoxBase.CustomValueSetEvent 事件。如需启用自定义输入，请设置 allowCustomValue 属性为 true。

<entityComboBox dataContainer="userDc"
                property="department"
                itemsContainer="departmentsDc"
                id="departmentField"
                allowCustomValue="true"/>
@ViewComponent
private CollectionContainer<Department> departmentsDc;

@ViewComponent
private EntityComboBox<Department> departmentField;

@Autowired
private DataManager dataManager;

@Subscribe("departmentField")
public void onDepartmentFieldCustomValueSet(ComboBoxBase.CustomValueSetEvent
                                                        <ComboBox<Department>> event) {
    Department department = dataManager.create(Department.class); (1)
    department.setName(event.getDetail()); (2)
    departmentsDc.getMutableItems().add(department); (3)
    departmentField.setValue(department);
}
1 创建一个新实例合并至上下文。
2 为新创建的 department 实体设置名称。
3 添加合并的实体。

XML 内部元素

actions - tooltip