valuePicker 值选择器

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

XML 元素

valuePicker

Java 类

JmixValuePicker

基本用法

在线示例

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

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

XML
<valuePicker id="valuePicker" dataContainer="customerDc" property="name" allowCustomValue="true"
             label="Name" helperText="Generate or type a customer name">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate name"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>
Java
@ViewComponent
protected InstanceContainer<Customer> customerDc;
@Autowired
protected Metadata metadata;

protected List<String> names = List.of("Katherine", "John", "Andy", "Edward", "George",
        "Philipp", "Dora", "James", "Daniel", "Michael", "Claire", "Joan", "Peter", "Martin");
@Subscribe
protected void onInit(InitEvent event) {
    Customer customer = metadata.create(Customer.class);
    customer.setName(getRandomName());
    customerDc.setItem(customer);
}
@Subscribe("valuePicker.generate")
protected void onValuePickerGenerateActionPerformed(ActionPerformedEvent event) {
    customerDc.getItem().setName(getRandomName());
}

@Subscribe("valuePicker")
protected void onValuePickerCustomValueChange(CustomValueSetEvent<JmixValuePicker<String>, String> event) {
    customerDc.getItem().setName(event.getText());
}

protected String getRandomName() {
    return names.get(RandomUtils.secure().randomInt() % names.size());
}

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

<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
    <valuePicker id="valuePicker" dataContainer="customerDc" property="name" allowCustomValue="true"
                 label="Name" helperText="Generate or type a customer name">
        <actions>
            <action id="generate" icon="REFRESH" description="Generate name"/>
            <action id="value_clear" type="value_clear"/>
        </actions>
    </valuePicker>

customerDc 实例容器存储一个 Customer 实体。该组件绑定到 name 属性。

操作

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

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

预定义操作

在线示例

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

<valuePicker id="valuePicker1" label="Random string">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate value"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>

用 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="valuePicker1" label="Random string">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate value"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>

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

@ViewComponent
protected JmixValuePicker<String> valuePicker1;
@Subscribe("valuePicker1.generate")
protected void onValuePicker1GenerateActionPerformed(ActionPerformedEvent event) {
    generateValue(valuePicker1);
}
protected void generateValue(JmixValuePicker<String> valuePicker) {
    valuePicker.setValue(RandomStringUtils.secure().nextAlphabetic(5, 10));
}

自定义值

在线示例

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

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

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

示例：

@ViewComponent
protected JmixValuePicker<String> valuePicker2;
@Subscribe("valuePicker2")
protected void onValuePicker2CustomValueChange(CustomValueSetEvent<JmixValuePicker<String>, String> event) {
    event.getSource().setValue(event.getText());
}

格式化器

为组件添加一个 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

样式版本

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

下面是 valuePicker 的特殊属性：

名称 描述 默认值

allowCustomValue

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

false

下面是 valuePicker 支持的其他通用属性：

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

事件和处理器

下面是 valuePicker 的特殊事件和处理器：

名称 描述

CustomValueSetEvent

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

formatter

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

validator

验证组件值。

下面是 valuePicker 支持的其他通用事件：

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - statusChangeHandler

XML 内部元素

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