ValuePicker

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

ValuePickerValuesPickerEntityPickerEntityComboBox 的基类。

组件的 XML 名称:valuePicker

基本用法

ValuePicker 可以有标题和自定义或预定义操作:

value picker1

定义 ValuePicker 的示例,这里 标题 从本地消息包获取,并带有两个 操作

<valuePicker id="valuePicker"
             caption="msg://code">
    <actions>
        <action id="generate"
                icon="REFRESH"
                description="msg://description"/>
        <action id="clear" type="value_clear"/>
    </actions>
</valuePicker>

如需创建关联至数据的 ValuePicker,可以用 XML 的 dataContainerproperty 属性:

<data>
    <instance id="userDc"
              class="ui.ex1.entity.User">
        <fetchPlan extends="_base"/>
        <loader/>
    </instance>
</data>
<layout spacing="true">
    <vbox spacing="true" id="vBox">
        <valuePicker id="loginValuePicker"
                     caption="msg://ui.ex1.entity/User.login"
                     dataContainer="userDc"
                     property="login">
            <actions>
                <action id="generate" icon="REFRESH"/>
            </actions>
        </valuePicker>

上面的例子中,界面为具有 login 属性的 User 实体定义了 userDc 数据容器。在 ValuePicker 中,dataContainer 属性指向 userDc 数据容器,property 包含实体 login 属性的名称。

默认情况下,用户不能手动输入值。如果设置 fieldEditable 属性为 true,可以启用手动输入。要注意,输入的值不会设置到数据模型。如需处理用户输入,使用 FieldValueChangeEvent 监听器。

下面的例子中,User 实体有 age 属性。我们在 XML 中定义 ageValuePicker,其中 fieldEditable="true"

<valuePicker id="ageValuePicker"
             caption="msg://ui.ex1.entity/User.age"
             dataContainer="userDc"
             property="age"
             fieldEditable="true">
    <actions>
        <action id="clear" type="value_clear"/>
    </actions>
</valuePicker>

现在用户可以手动输入值了。如需处理该值(解析为字符串),在控制器订阅 FieldValueChangeEvent

@Autowired
private ValuePicker<Integer> ageValuePicker;

@Subscribe("ageValuePicker")
public void onAgeValuePickerFieldValueChange(ValuePicker.FieldValueChangeEvent<Integer> event) {
    String text = event.getText(); (1)
    notifications.create()
            .withCaption("Entered value: " + text)
            .show();
    if (!Strings.isNullOrEmpty(text)) {
        ageValuePicker.setValue(Integer.parseInt(text)); (2)
    }
}
1 获取用户输入字符串
2 将解析的值复制给 ageValuePicker

操作

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

预定义操作

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

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

typeid 属性在 XML 中设置预定义操作。

addAction() 编程式设置:

@Autowired
protected ValuePicker<String> loginValuePicker;
@Autowired
protected Actions actions;

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

自定义操作

如需在 XML 中定义自定义操作,可以使用内部的 actions 元素。为 action 指定 idicon 属性:

<valuePicker id="loginValuePicker"
             caption="msg://ui.ex1.entity/User.login"
             dataContainer="userDc"
             property="login">
    <actions>
        <action id="generate" icon="REFRESH"/>
    </actions>
</valuePicker>

然后在界面控制器订阅 Action.ActionPerformedEvent 实现自定义逻辑:

@Subscribe("loginValuePicker.generate") (1)
protected void onLoginValuePickerGenerate(Action.ActionPerformedEvent event) {
    loginValuePicker.setValue(RandomStringUtils.randomAlphabetic(5, 10));
}
1 @Subscribe 注解包含 ValuePickerid 以及操作的 id,以“.”分隔。

验证

如需验证 ValuePicker 组件的值,可以在内部的 validators 元素使用 validator

ValuePicker 可以使用下列预定义的 validators:

下面例子中,我们展示为 countryValidField 使用 NotNullValidator

<entityComboBox id="countryValidField"
                caption="Select a country"
                optionsContainer="countriesDc">
    <validators>
        <notNull/>
    </validators>
</entityComboBox>

事件和处理器

如需使用 Jmix Studio 生成处理器的桩代码,需要在界面 XML 描述或者 Component Hierarchy 面板选中该组件,然后用 Component Inspector 面板的 Handlers 标签页生成。

或者可以使用界面控制器顶部面板的 Generate Handler 按钮。

ContextHelpIconClickHandler

FieldIconProvider

参阅 FieldIconProvider

FieldValueChangeEvent

格式化器

参阅 Formatter

Validator

为组件添加 validator 实例。如果值验证失败,validator 必须抛出 ValidationException 异常。

如果 预定义 的验证器不能满足要求,可以添加自定义的验证器实例:

@Install(to = "iconComboBox", subject = "validator")
protected void iconComboBoxValidator(FontAwesome icon) {
    if (icon != null)
        if (icon == FontAwesome.FILE_PDF_O)
            throw new ValidationException("The file type you selected " +
                    "is not currently supported");
}

ValueChangeEvent

参阅 ValueChangeEvent

ValuePicker XML 属性

可以使用 Studio 界面设计器的 Component Inspector 面板查看和编辑组件的属性。

ValuePicker XML 元素