valuePicker 值选择器

在线示例

valuePicker 组件可展示任意类型的值。由文本框和一组由操作定义的按钮组成。

XML 元素

valuePicker

Java 类

JmixValuePicker

XML 属性

id - alignSelf - allowCustomValue - 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

事件和处理器

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

XML 内部元素

actions - formatter - prefix - suffix - tooltip - validator

基本用法

该组件主要用来选择复杂的值，即在选择过程中涉及某种操作的值。

value picker basic

下面是 valuePicker 的示例，具有 label 并带有两个操作：

<valuePicker id="valuePicker" label="Code">
    <actions>
        <action id="generate" icon="REFRESH"/>
        <action id="valueClear" type="value_clear"/>
    </actions>
</valuePicker>

如需创建关联至数据的 valuePicker，可以用 XML 的 dataContainer 和 property 属性：

<data>
    <instance class="com.company.onboarding.entity.Step" id="stepDc"> (1)
        <fetchPlan extends="_base"/> (2)
        <loader id="stepDl"/>
    </instance>
</data>
<layout>
    <valuePicker label="msg://com.company.onboarding.entity/Step.name"
                 dataContainer="stepDc"
                 property="name"> (3)
        <actions>
            <action id="lookup" icon="ELLIPSIS_DOTS_H"/>
            <action id="valueClear" type="value_clear"/>
        </actions>
    </valuePicker>
</layout>
1 Step 实体的 InstanceContainer 容器。
2 容器内实体的内联 fetch plan。
3 将组件与数据容器和属性进行关联。dataContainer 属性使用 stepDc 数据容器，property 引用 name 实体属性。

操作

可以给 valuePicker 设置自定义或预定义的操作，并作为按钮显示在右侧。 定义操作可以用 XML 中用内部的 actions 元素或者在控制器中用 addAction() 方法编程式添加。

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

预定义操作

框架只提供了一个预定义操作 - value_clear：

<action id="valueClear" type="value_clear"/>

用 type 和 id 属性在 XML 中设置预定义操作。

用 addAction() 编程式设置：

@ViewComponent
private JmixValuePicker<String> loginValuePicker;

@Autowired
private Actions actions;

@Subscribe
public void onInit(InitEvent event) {
    loginValuePicker.addAction(actions.create(ValueClearAction.ID));
}

自定义操作

如需在 XML 中定义自定义操作，可以使用内部的 actions 元素。为 action 指定 id 和 icon 属性：

<valuePicker id="generateLoginPicker" label="Login">
    <actions>
        <action id="valueClear" type="value_clear"/>
        <action id="generate" icon="REFRESH"/>
    </actions>
</valuePicker>

然后在视图控制器订阅 ActionPerformedEvent 实现自定义逻辑：

@ViewComponent
private JmixValuePicker<String> generateLoginPicker;

@Subscribe("generateLoginPicker.generate")
public void onGenerateLoginPickerGenerate(ActionPerformedEvent event) {
    generateLoginPicker.setValue(RandomStringUtils.randomAlphabetic(5, 10));
}

自定义值

valuePicker 可以配置为接收自定义值。

当 allowCustomValue 属性设置为 true 时，用户可以手动输入自定义字符串值，并触发 CustomValueSetEvent。

valuePicker 不会对用户输入的自定义内容做任何处理。如果需要处理，请使用 CustomValueSetEvent 事件的处理方法。

示例：

@Autowired
private Notifications notifications;

@ViewComponent
private JmixValuePicker<String> vPicker;

@Subscribe("vPicker")
public void onVPickerCustomValueSet(
        CustomValueSetEvent<JmixValuePicker<String>, Object> event) {
    String text = event.getText(); (1)
    notifications.create("Entered value: " + text)
            .show();
    if (!Strings.isNullOrEmpty(text))
        vPicker.setValue(text); (2)
}
1 以字符串类型获取用户输入。
2 将值设置给 vPicker。

格式化器

为组件添加一个 formatter 实例。

下面的示例中，我们展示 vPicker 值选择器中 formatter 的用法：

@Install(to = "vPicker", subject = "formatter")
private String vPickerFormatter(String value) {
    return value != null ? "Code: " + value : null;
}

如需以编程方式添加 formatter，使用组件的 setFormatter() 方法。

验证

如需检查 valuePicker 组件输入的值，可以在内部元素 validators 中添加一个 validator元素。

valuePicker 可以使用下列预定义的验证器：

XML 元素

validators

预定义验证器

custom - decimalMax - decimalMin - digits - doubleMax - doubleMin - email - max - min - negativeOrZero - negative - notBlank - notEmpty - notNull - positiveOrZero - positive - regexp - size

XML 属性

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

名称

描述

默认值

allowCustomValue

默认情况下，用户无法手动输入值。但如果设置 allowCustomValue 为 true，则允许用户手动输入。注意，此时手动输入的值并没有设置给数据模型，而需要通过 CustomValueSetEvent 事件对输入值进行自定义处理。参阅 自定义值。

false

事件和处理器

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

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

名称

描述

CustomValueSetEvent

io.jmix.flowui.kit.component.valuepicker.CustomValueSetEvent 当用户输入非空自定义值时触发。如需允许用户输入，需要设置 allowCustomValue 属性为 true。参阅 自定义值。

formatter

为组件添加一个 formatter 实例。参阅 Formatter。