select 单选

基本用法

selectcomboBox 类似。

下列情况请使用 select

  • 当不需要用户输入对选项进行过滤时。

  • 选项列表需要是紧凑的。如果选项对于 radioButtonGroup 过多的话,可以用该组件。

select 最基本的用法就是从枚举中选择值:

<select itemsEnum="com.company.onboarding.entity.DayOfWeek"
        label="Select the day of week"/>
select basics

数据绑定

数据绑定是指将组件与 数据容器 进行关联。可视化组件或相应数据容器中的更改可以触发彼此的更新。有关详细信息,请参阅 使用数据组件

默认情况下,Jmix Studio 在创建带有枚举类型属性的实体详情视图时会生成 select。例如,User 实体的 onboardingStatus 属性是 OnboardingStatus 枚举类型。

<data>
    <instance id="userDc"
              class="com.company.onboarding.entity.User">
        <fetchPlan extends="_base"/>
        <loader id="userDl"/>
    </instance>
</data>
<layout>
    <formLayout id="form" dataContainer="userDc">
        <select id="onboardingStatusField"
                property="onboardingStatus"/>
    </formLayout>
</layout>

下面的示例演示如何用 select 组件选择用户所属的部门:

<data>
    <instance class="com.company.onboarding.entity.User"
              id="userDc"> (1)
        <fetchPlan extends="_base"> (2)
            <property name="department" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="userDl"/>
    </instance>
    <collection class="com.company.onboarding.entity.Department"
                id="departmentsDc"> (3)
        <fetchPlan extends="_base"/>
        <loader id="departmentsDl">
            <query>
                <![CDATA[select e from Department e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/> (4)
</facets>
<layout>
    <select dataContainer="userDc"
            property="department"
            itemsContainer="departmentsDc"/> (5)
</layout>
1 数据容器包含当前编辑的 User 实例。
2 定义获取作为选项的 Department 实例的 fetch plan。
3 包含 Department 实例集合的数据容器。
4 数据加载器自动加载为组件提供选项。
5 将组件与数据容器和属性进行关联。通过 itemsContainer 属性指定选项列表。

选项的构建

可以通过下列方法为 select 设置选项列表:

选项列表

<select id="selectItems" datatype="int"/>

setItems() 方法可以编程式地设置选项列表。

@ViewComponent
private JmixSelect<Integer> selectItems;

@Subscribe
public void onInit(final InitEvent event) {
    selectItems.setItems(1, 2, 3, 4, 5);
}

选项映射

<select id="selectMaps" datatype="int"/>

ComponentUtils.setItemsMap() 可以显式地为选项条目设置字符串标签。

@ViewComponent
private JmixSelect<Integer> selectMaps;

@Subscribe
public void onInit(final InitEvent event) {
    Map<Integer, String> map = new LinkedHashMap<>();
    map.put(2, "Poor");
    map.put(3, "Average");
    map.put(4, "Good");
    map.put(5, "Excellent");
    ComponentUtils.setItemsMap(selectMaps, map);
}

选项枚举

如果使用枚举,则可以通过声明式或编程式的方法将枚举值设置为选项。

下面的示例是声明式用法。

<select id="selectEnum"
        itemsEnum="com.company.onboarding.entity.DayOfWeek"/>

下面的示例是编程式用法。

@ViewComponent
private JmixSelect<DayOfWeek> selectEnum;

@Subscribe
public void onInit(final InitEvent event) {
    selectEnum.setItems(DayOfWeek.class);
}

禁用选项

选项可以禁用,此时用户无法选择这些选项,但是这些选项也可能在不同的条件下允许选择。

使用 itemEnabledProvider 可以根据特定条件动态配置每个选项的启用状态。禁用的选项显示为灰色,用户无法选择。所有选项默认启用。

@Install(to = "select", subject = "itemEnabledProvider")
private boolean selectItemEnabledProvider(final Department department) {
    return department == null || department.getHrManager() != null;
}

空选项

select 组件提供展示一个空选项的功能,在默认值为空或“没有选择任何选项”的场景可以用到。

emptySelectionAllowed 设置是否允许用户选择空值。当设置为 true 时,选项列表中会显示一个空白选项。

空选项可以通过 emptySelectionCaption 属性进行自定义。

<select id="sizeSelect"
        emptySelectionAllowed="true"
        emptySelectionCaption="Unknown size"
        datatype="string"/>

emptySelectionAllowed = true 时,使用 emptySelectionCaption 属性设置空白选项的标题。用于在选项列表中显示。

当选择空选项时,组件显示的值为 itemLabelGenerator 提供的 null 选项值,或者由 placeholder 属性设置的占位符,如果占位符也没有设置,则显示空白。

@Install(to = "sizeSelect", subject = "itemLabelGenerator")
private String sizeSelectItemLabelGenerator(final String t) {
    return t != null ? t : sizeSelect.getEmptySelectionCaption();
}

自定义选项标签

通过 itemLabelGenerator 可以自定义 radioButtonGroup 组件中选项的显示标签,即控制用户看到的文本,从而能够以更友好或特定于上下文的方式显示信息。

@Install(to = "customItemsSelect", subject = "itemLabelGenerator")
private String customItemsSelectItemLabelGenerator(final Department t) {
    return t.getHrManager() != null
            ? t.getName() + "[Manager: " + t.getHrManager().getFirstName() +
            " " + t.getHrManager().getLastName() + "]"
            : t.getName();
}

itemLabelGenerator 控制下拉列表中每个选项显示的标签,以及 select 组件输入框中已选择项的标签。

textRenderer 仅控制下拉列表中每个选项显示的标签。

@Install(to = "departmentSelect", subject = "textRenderer")
private String departmentSelectTextRenderer(final Department t) {
    return t.getName() + ", number #" + t.getNum();
}
textRenderer 不会影响 select 组件输入框中已选择项的标签。

如果仅需自定义下拉列表中的标签,可以通过该功能提高选项的辨析度、添加其他信息或根据所选对象的属性调整标签。

选项渲染

框架提供了自定义选项渲染的功能。渲染器会对每个选项生效并创建选项的外观组件。

可以使用 setRenderer() 方法或 @Supply 注解实现。

@Autowired
private UiComponents uiComponents;

@Supply(to = "selectWithRenderer", subject = "renderer")
private ComponentRenderer<Button, Department> selectWithRendererRenderer() {
    return new ComponentRenderer<>(department -> {
        Button button = uiComponents.create(Button.class);
        button.setText(department.getName());
        button.setIcon(VaadinIcon.DESKTOP.create());
        return button;
    });
}

Overlay

Overlay 是一个半透明或不透明的图层,用于显示选项的下拉列表。

overlayClass 属性可以为 overlay 元素添加自定义的 CSS 类。

<select itemsEnum="com.company.onboarding.entity.DayOfWeek"
        overlayClass="my-custom-overlay"/>

在 css 文件中自定义样式:

vaadin-select-overlay.my-custom-overlay::part(overlay){
    background-color: #ecfcf9;
    border-radius: 5px;
}

样式版本

使用 themeNames 属性可以调整文本对齐、帮助文本显示位置或组件的尺寸。

对齐方式

支持三种对齐方式:align-left(默认)、align-rightalign-center

select alignment
XML 代码
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="align-left"
        helperText="The align-left alignment"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="align-center"
        helperText="The align-center alignment"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="align-right"
        helperText="The align-right alignment"/>

帮助文本显示位置

设置 helper-above-field 会将帮助文字显示在控件上方而不是默认的下方:

select helper above field
XML 代码
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        label="Onboarding status"
        helperText="Helper text with helper-above-field"
        themeNames="helper-above-field"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        label="Onboarding status"
        helperText="Helper text without helper-above-field"/>

尺寸

支持两种尺寸:默认大小或 small

select size
XML 代码
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        helperText="Default size"/>
<select itemsEnum="com.company.onboarding.entity.OnboardingStatus"
        themeNames="small"
        helperText="Small size"/>

XML 属性

在 Jmix 中,所有组件都有一些作用一致的 通用属性

下面是 select 的特殊属性:

名称

描述

默认值

emptySelectionAllowed

设置用户是否可以不选择。参阅 空白选项

false

emptySelectionCaption

emptySelectionAllowed = true 时,设置空白选项的标签。参阅 空白选项

空字符串 ""

itemsContainer

定义包含选项列表的数据容器。组件显示实体的实例名称。参阅 数据绑定

itemsEnum

定义用于创建选项列表的枚举类。参阅 选项枚举

overlayClass

定义需要在 overlay 元素上设置的 CSS 类列表,以空格分隔。参阅 Overlay

事件和处理器

在 Jmix 中,所有组件都有一些 通用事件和处理器,可以按相同的方法设置。

下面是 select 的特殊事件和处理器:

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

名称

描述

InvalidChangeEvent

com.vaadin.flow.component.select.Select.InvalidChangeEvent 当组件的 invalid 状态变化时发送。

OpenedChangeEvent

com.vaadin.flow.component.select.Select.OpenedChangeEvent 当组件的选项弹窗 opened 状态变化时发送。

itemEnabledProvider

itemEnabledProvider 作用于每个选项,用于判断该选项是否启用(true)或禁用(false)。参阅 禁用选项

itemLabelGenerator

自定义每个选项的显示标签。参阅 自定义选项标签

renderer

设置选项的渲染器。参阅 选项渲染

textRenderer

设置选项的文本渲染器。参阅 自定义选项标签.

参考