entityComboBox 实体下拉框

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

事实上,entityComboBoxcomboBoxentityPicker 的组合。

  • XML 元素:entityComboBox

  • Java 类:EntityComboBox

基本用法

满足下列情况可以使用 entityComboBox

  • 字段值是实体实例。

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

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

  • 用户需要过滤功能。

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

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

entity combobox basics

如需创建连接至数据的 entityComboBox,可以用 XML 的 dataContainerproperty 属性。而 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 entityComboBoxdepartmentsDc 作为选项容器,展示部门列表。

如果选项数量很大(数千个或更多),请不要使用 entityComboBoxentityComboBox 会将全部选项列表加载到用户的浏览器和服务器内存中。如需从大量选项列表中进行选择,请使用 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 属性

allowCustomValue

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

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

默认值为 false

itemsContainer

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

opened

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

默认值为 false

事件和处理器

在 Jmix Studio 生成处理器桩代码时,可以使用 Jmix UI 组件面板的 Handlers 标签页或者视图类顶部面板的 Generate Handler 添加,也可以通过 CodeGenerate 菜单(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 内部元素