comboBox 下拉列表

在线示例

comboBox 支持用户从下拉列表中选择单一值。

  • XML 元素：comboBox

  • Java 类：JmixComboBox

基本用法

满足下列情况可以使用 comboBox：

  • 用户需要选择单一选项。

  • 选项列表应该比较紧凑。如果选项列表对于 radioButtonGroup 太长时，用下拉列表更方便。

Jmix Studio 在创建实体详情视图时，会给实体的枚举属性生成 comboBox 组件。例如，User 实体有 onboardingStatus 属性，这是一个 OnboardingStatus 枚举类型的属性。

combo box basic

在 comboBox 元素中，dataContainer 属性使用 userDc 数据容器，property 引用 onboardingStatus 实体属性。这里，实体的属性为枚举类型，下拉列表显示所有枚举值的本地化名称。

<data>
    <instance class="com.company.onboarding.entity.User" id="userDc">
        <fetchPlan extends="_base"/>
        <loader id="userDl"/>
    </instance>
</data>
<layout>
    <comboBox id="comboBox"
              dataContainer="userDc"
              property="onboardingStatus"
              label="Onboarding status"/>
</layout>

自定义选项

comboBox 的选项列表还可以通过 setItems() 方法设置。

首先在 XML 描述中声明组件：

<data>
    <instance class="com.company.onboarding.entity.Step" id="stepDc">
        <fetchPlan extends="_base"/>
        <loader id="stepDl"/>
    </instance>
</data>
<layout>
    <comboBox id="durationComboBox"
              dataContainer="stepDc"
              property="duration"/>
</layout>

然后将组件注入控制器，在 onInit() 方法中设置选项列表：

@ViewComponent
private JmixComboBox<Integer> durationComboBox;

@Subscribe
public void onInit(InitEvent event) {
    durationComboBox.setItems(new ArrayList<>(Arrays.asList(1,2,3,4,5)));
}

组件的下拉列表中会显示 1、2、3、4 和 5。选择的值会设置到 stepDc 数据容器中的 duration 属性上。

验证

如需检查 comboBox 组件输入的值，可以通过内部元素 validators 使用 validator。

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

XML 属性

id - alignSelf - allowCustomValue - autoOpen - autofocus - classNames - clearButtonVisible - colspan - dataContainer - enabled - errorMessage - height - helperText - invalid - itemsEnum - label - maxHeight - maxWidth - minHeight - minWidth - pageSize - pattern - placeholder - property - readOnly - required - requiredIndicatorVisible - requiredMessage - tabIndex - themeNames - title - visible - width

allowCustomValue

Vaadin

如果 allowCustomValue 属性为 true，用户可以输入不匹配任何选项的字符串值，此时会触发 CustomValueSetEvent。

注意，comboBox 不会自动处理自定义字符串。请使用 CustomValueSetEvent 进行处理。

默认值为 false。

autoOpen

Vaadin

当 autoOpen 属性设置为 true 时，comboBox 的下拉列表会在控件获得焦点（鼠标点击或手指点击）时或用户输入内容时自动展示。

设置为 false 禁用该功能。

itemsEnum

定义枚举类作为控件的选项列表。下拉列表中会显示枚举值的本地化名称；组件的值则为枚举的值。

<comboBox label="Onboarding status"
          itemsEnum="com.company.onboarding.entity.OnboardingStatus"/>

pageSize

Vaadin

设置每个请求发送选项的最大数量，值必须大于 0。参考 com.vaadin.flow.component.combobox.ComboBoxBase.setPageSize() 方法。

默认分页大小为 50。

事件和处理器

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

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

CustomValueSetEvent

当用户输入非空值，且不匹配任何已有选项时，发出 com.vaadin.flow.component.combobox.ComboBoxBase.CustomValueSetEvent 事件。如需启用自定义输入，请设置 allowCustomValue 属性为 true。

<comboBox id="colorComboBox"
          label="Select the color"
          allowCustomValue="true"/>
@ViewComponent
private JmixComboBox<String> colorComboBox;

@Subscribe
public void onInit(InitEvent event) {
    colorComboBox.setItems(new ArrayList<>
            (Arrays.asList("White", "Red", "Blue", "Grey")));
}
@Subscribe("colorComboBox")
public void onColorComboBoxCustomValueSet(CustomValueSetEvent<ComboBox<String>> event) {
    colorComboBox.setValue(event.getDetail());
}

itemLabelGenerator

com.vaadin.flow.component.ItemLabelGenerator 可以自定义某个选项展示给用户的名称。示例：

@Install(to = "colorComboBox", subject = "itemLabelGenerator")
private String colorComboBoxItemLabelGenerator(String item) {
    return item.toUpperCase();
}

XML 内部元素

tooltip - validator

参考

Vaadin 文档