选择器控件 - CUBA 框架开发者手册

3.5.2.1.31. 选择器控件

在线示例

API 文档

PickerField 在文本字段中显示实体实例，并在用户单击右侧的按钮时执行操作。

该组件的 XML 名称： pickerField

PickerField 有一个使用规则，就是它只用于引用类型的实体属性。使用时为组件指定 dataContainer 和 property 属性就可以了：
```
<data>
    <instance id="carDc" class="com.haulmont.sample.core.entity.Car" view="carEdit">
        <loader/>
    </instance>
</data>
<layout>
    <pickerField dataContainer="carDc" property="color"/>
</layout>
```
在上面的例子中，界面为具有 color 属性的 Car 实体定义了 id 为 carDc 的数据容器。在 pickerField 元素中，通过 dataContainer 属性连接到此数据容器，并给 property 属性设置了实体属性的名称。实体属性应该引用另一个实体，在上面的示例中就是 Color 实体。

对于 PickerField，可以定义任意数量的操作，这些操作在组件右侧显示为按钮。

操作的定义可以使用 actions 嵌套元素在 XML 描述中完成，也可以使用 addAction() 方法在控制器中以编程方式完成。

平台提供一组标准的 PickerField 操作：picker_lookup 、picker_clear 、picker_open。它们分别执行关联实体的选择、清空组件以及打开所选关联实体的编辑界面。在 XML 中声明标准操作时，应当定义操作的标识符并使用 type 属性定义操作类型。

如果在声明组件时未定义 actions 元素中的动作，则 XML 加载器将默认为其定义 lookup 和 clear 操作。要添加一个默认操作，比如 open，就需要定义 actions 元素，如下所示：

<pickerField dataContainer="carDc" property="color">
    <actions>
        <action id="lookup" type="picker_lookup"/>
        <action id="open" type="picker_open"/>
        <action id="clear" type="picker_clear"/>
    </actions>
</pickerField>

action 元素能不能扩展，但可以按操作标识符来覆盖一组标准操作。所以必须明确定义所有需要的操作的标识符。该组件如下所示：

使用 addAction() 以编程方式设置标准操作。如果在组件的 XML 描述中没有 actions 嵌套元素，就可以使用这个方法添加缺少的操作：

@Inject
protected PickerField<Color> colorField;

@Subscribe
protected void onInit(InitEvent event) {
    colorField.addAction(actions.create(OpenAction.class));
}

如果组件是在控制器中创建的，则它将不会包含默认操作，需要显式添加所有需要的操作：

@Inject
private InstanceContainer<Car> carDc;
@Inject
private UiComponents uiComponents;
@Inject
private Actions actions;

@Subscribe
protected void onInit(InitEvent event) {
    PickerField<Color> colorField = uiComponents.create(PickerField.NAME);
    colorField.setValueSource(new ContainerValueSource<>(carDc, "color"));
    colorField.addAction(actions.create(LookupAction.class));
    colorField.addAction(actions.create(OpenAction.class));
    colorField.addAction(actions.create(ClearAction.class));
    getWindow().add(colorField);
}

可以通过订阅 ActionPerformedEvent 事件来自定义标准操作的行为并提供自定义的实现。比如，可以通过如下方式使用特定的查找界面：

@Inject
private ScreenBuilders screenBuilders;
@Inject
private PickerField<Color> pickerField;

@Subscribe("pickerField.lookup")
protected void onPickerFieldLookupActionPerformed(Action.ActionPerformedEvent event) {
        screenBuilders.lookup(pickerField)
                 .withScreenClass(CustomColorBrowser.class)
                 .build()
                 .show();
}

更多信息，请参阅打开界面部分。

可以在 XML 描述中的 actions 嵌套元素中定义任何操作，这些操作的逻辑可以在操作的事件中实现，例如：

<pickerField dataContainer="orderDc" property="customer">
    <actions>
        <action id="lookup"/>
        <action id="show" icon="PICKERFIELD_OPEN" caption="Show"/>
    </actions>
</pickerField>

@Inject
private PickerField<Customer> pickerField;

@Subscribe("pickerField.show")
protected void onPickerFieldShowActionPerformed(Action.ActionPerformedEvent event) {
    CustomerEdit customerEdit = screenBuilders.editor(pickerField)
            .withScreenClass(CustomerEdit.class)
            .build();
    customerEdit.setDiscount(true);
    customerEdit.show();
}

操作的声明式创建和编程式创建在操作部分有描述。

可以在不绑定实体的情况下使用 PickerField，即不设置 dataContainer 和 property属性。在这种情况下，metaClass 属性应该用于指定 PickerField 的实体类型。例如：

<pickerField id="colorField" metaClass="sample_Color"/>

可以通过将组件注入控制器并调用其 getValue() 方法来获取所选实体的实例。

要正确使用 PickerField 组件，需要设置 metaClass 属性，或者同时设置 dataContainer 和property 属性。

可以在 PickerField 中使用键盘快捷键，有关详细信息，请参阅快捷键。

PickerField 组件可以在左边有一个图标。下面的例子在界面控制器中使用 setOptionIconProvider() 提供的方法。"cancel" 图标会在字段值是 null 的时候显示，而 "chain" 图标会在其它情况显示。

@Inject
private PickerField<Customer> pickerField;

protected String generateIcon(Customer customer) {
    return (customer!= null) ? "icons/chain.png" : "icons/cancel.png";
}

@Subscribe
private void onInit(InitEvent event) {
    pickerField.setOptionIconProvider(this::generateIcon);
}

pickerField 的属性: align - caption - captionAsHtml - captionProperty - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - metaClass - property - required - requiredMessage - stylename - tabIndex - visible - width
pickerField 的元素: actions - validator
API: addAction - addValueChangeListener - commit - discard - isModified - setContextHelpIconClickHandler - setOptionCaptionProvider - setOptionIconProvider