entityPicker 实体选择器

entityPicker 支持用户从查找视图中选择单一 实体 实例并进行相关操作。

XML 元素

entityPicker

Java 类

EntityPicker

基本用法

在线示例

当字段值是实体对象时，通常使用 entityPicker 组件。支持用户选择特定实体实例并执行相关操作。

点击查找按钮可以打开一个显示实体实例 列表视图 的弹窗：

与应用程序中的其他视图一样，这个视图也是可以配置的，支持提供多个属性帮助用户找到需要的实体实例。与 entityComboBox 实体下拉框 相比能提供更多的上下文。

当实例数量较大时，会在浏览列表时动态加载其他实例。

下面的示例演示使用 entityPicker 组件选择用户所属的部门：

该示例需要先为部门实体定义 列表视图。 
<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 中添加 action，可以在界面 XML 或者 Jmix UI 结构面板中选择组件，然后点击组件面板的 Add 按钮。

使用预定义操作

当 Studio 在详情视图中生成 entityPicker 时，还会同时生成两个预定义的操作：entity_lookup 和 entity_clear。此外，还支持 entity_open、entity_openComposition 和 entity_read 操作。

用 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 元素。为 action 指定 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>

然后在视图控制器订阅 Action.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();
}

可以用 Studio 生成处理 Action.ActionPerformedEvent 的桩代码。

编程式添加操作

使用 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

XML 属性

下面是 entityPicker 的特殊属性：

名称 描述 默认值

allowCustomValue

是否允许用户输入选项中没有的值。

—

metaClass

在使用 entityPicker 不绑定数据容器时，需要设置 metaClass，指定选项实体的类名。

—

下面是 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

XML 内部元素

一个 entityPicker 可以包含 actions、formatter、prefix、suffix、tooltip 和 validator 作为其内部元素。