ValuesPicker

ValuesPicker - 多值选择器 组件可以处理任意类型值的列表。由文本框和一组由操作定义的按钮组成。

如果需要通过操作编辑值列表而不是通过文本框,那么使用 ValuesPicker 会比较方便。

ValuesPickerTagPicker 的基类。与 ValuePicker 有相同的 API。

组件的 XML 名称:valuesPicker

基本用法

ValuesPicker 可以有标题、描述以及自定义或预定义操作:

values picker1

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

<valuesPicker id="stringsValuesPicker"
              caption="Favourite colors">
    <actions>
        <action id="select" type="values_select">
            <properties>
                <property name="javaClass" value="java.lang.String"/>
            </properties>
        </action>
        <action id="clear" type="value_clear"/>
    </actions>
</valuesPicker>

操作

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

预定义操作

框架提供了 value_clearvalues_select 预定义操作。

values_select 操作使用一个值选择界面为 ValuesPicker 设置值。值选择界面会生成一个特定的组件用于选择值,或者根据传入的值类型创建值。

values_select 操作可用来选择任意类型的值,示例:

  • Java 类型,例如,StringIntegerLongDoubleBigDecimalDateLocalDateLocalTimeLocalDateTimeOffsetTimeOffsetDateTimeDateTimeUUID 以及 java.sql.Datejava.sql.Time

    javaClass 属性设置选择值的 Java 类型。

    上面 的示例中,values_select 操作使用 java.lang.String Java 类型。当用户点击选择按钮时,会展示 Select Value(选择值) 界面。用户可以在这个界面新建值或者从值列表中添加/删除。用户可以点击 Add(添加) 按钮或按下 Enter 添加值。

    valuesPicker

    对于 UUID Java 类,Select Value(选择值) 界面会生成 MaskedField

    对于 date 类型,会生成 DateField

    resolution 属性为 DateField 组件设置精度:

    <action id="select" type="values_select">
        <properties>
            <property name="javaClass" value="java.util.Date"/>
            <property name="resolution" value="MONTH"/>
        </properties>
    </action>

    timeZone 属性为 DateField 组件设置时区:

    对于 time 类型,会生成 TimeField

    对于其他类型,会生成 TextField

  • Enum values

    enumClass 属性设置选择值的枚举类型。

    <valuesPicker id="valuePicker"
                  caption="Hobbies">
        <actions>
            <action id="select" type="values_select">
                <properties>
                    <property name="enumClass" value="ui.ex1.entity.Hobby"/>
                </properties>
            </action>
            <action id="clear" type="value_clear"/>
        </actions>
    </valuesPicker>

    对于枚举值,Select Value(选择值) 界面会生成 ComboBox

    values picker enum
  • Entity instances

    entityName 属性设置选择值的实体名称。

    <valuesPicker id="valuePickerEnt">
        <actions>
            <action id="select" type="values_select">
                <properties>
                    <property name="entityName" value="uiex1_User"/>
                    <property name="useComboBox" value="true"/>
                </properties>
            </action>
            <action id="clear" type="value_clear"/>
        </actions>
    </valuesPicker>

    useComboBox 属性指定在值选择界面中是否用 ComboBox。默认为 false

    lookupScreenId 属性设置传入值选择界面的查找界面 id,用于选择实体。

值选择界面实现了 SelectValueController 接口。

selectValueScreenId 属性设置实现了 SelectValueController 接口的界面 id。

selectValueScreenClass 属性设置实现了 SelectValueController 接口的类或界面。

自定义操作

ValuesPicker 的自定义操作与 ValuePicker自定义操作 类似。

验证

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

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

下面例子中,我们展示为 validatedCheckBoxGroup 使用 SizeValidator

<checkBoxGroup id="validatedCheckBoxGroup"
               optionsContainer="customersDc"
               caption="The number of customers is limited from 2 to 5">
    <validators>
        <size min="2" max="5"/>
    </validators>
</checkBoxGroup>

事件和处理器

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

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

ContextHelpIconClickHandler

FieldIconProvider

参阅 FieldIconProvider

FieldValueChangeEvent

格式化器

参阅 Formatter

Validator

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

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

@Install(to = "validCheckBoxGroup", subject = "validator")
protected void validCheckBoxGroupValidator(Collection<EducationalStage> value) {
    if (value.contains(EducationalStage.NO) & value.size() > 1)
        throw new ValidationException("You cannot select the No Education " +
                "value together with other values");
}

ValueChangeEvent

参阅 ValueChangeEvent

ValuesPicker XML 属性

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

ValuesPicker XML 元素