listBox 列表选择器

listBox 支持用户从可滚动的列表选择单一值。

XML 元素

listBox

Java 类

JmixListBox

基本用法

在线示例

listBox 可以编程式通过 setItems() 设置。在特定的条目之间可以插入例如分隔符之类的组件。

XML
<vbox width="AUTO">
    <h4 text="Simple ListBox"/>
    <listBox id="listBox"/>
</vbox>
<vbox width="AUTO">
    <h4 text="ListBox with separator"/>
    <listBox id="listBox2"/>
</vbox>
Java
@ViewComponent
protected JmixListBox<String> listBox;
@ViewComponent
protected JmixListBox<String> listBox2;

@Subscribe
protected void onInit(InitEvent event) {
    List<String> items = List.of("Jmix", "Vaadin", "SpringBoot", "EclipseLink");
    listBox.setItems(items);
    listBox2.setItems(items);

    listBox.setValue("Jmix");
    listBox2.setValue("Jmix");

    listBox2.addComponents("Vaadin", new Hr());
}

数据容器中的条目

在线示例

使用 itemsContainer 将数据容器中的实体放入 listBox：

<data>
    <collection id="productsDc"
                class="io.jmix.uisamples.entity.Product"
                fetchPlan="_local">
        <loader id="productsDl">
            <query>
                <![CDATA[select e from Product e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <listBox itemsContainer="productsDc"/>
</layout>

枚举条目

使用 itemsEnum 将枚举值放入 listBox：

<listBox itemsEnum="com.company.onboarding.entity.OnboardingStatus"/>

禁用条目

在线示例

itemEnabledProvider 会在 listBox 的每个条目生效，以确定该条目是启用（true）还是禁用（false）。已禁用的条目显示为灰色，用户无法选择。默认情况下，所有条目均处于启用状态。

假设 listBox 显示一个用户列表。如果希望显示入职步骤状态为 "Completed" 的用户为启用，而禁用 "In progress" 或 "Not started" 状态的用户。

@ViewComponent
protected JmixListBox<Product> listBox;

@Subscribe
protected void onInit(InitEvent event) {
    initListBox();
}

protected void initListBox() {
    listBox.setItems(getListBoxItems());
    listBox.setItemEnabledProvider(product -> product.count() > 0);
}

@Supply(to = "listBox", subject = "renderer")
protected ComponentRenderer<Text, Product> listBoxRenderer() {
    return new ComponentRenderer<>(product -> new Text(product.getDisplayName()));
}

protected Collection<Product> getListBoxItems() {
    return List.of(
            new Product("TV set", 4),
            new Product("Keyboard", 13),
            new Product("Earphones", 0),
            new Product("Telephone", 23),
            new Product("Laptop", 0)
    );
}

示例中，itemEnabledProvider 检查每个用户的状态。只有 OnboardingStatus.COMPLETED 状态的用户会在 listBox 中显示为启用。

条目渲染

在线示例

框架支持为条目自定义渲染内容。可以使用 setRenderer() 方法或 @Supply 注解实现。

XML
<layout classNames="list-box-custom-renderer">
    <listBox id="listBox"/>
</layout>
Java
protected static final String PATH_PREFIX = "/META-INF/resources/icons/";

@ViewComponent
protected JmixListBox<Simpson> listBox;

@Autowired
protected UiComponents uiComponents;
@Autowired
protected Resources resources;

@Subscribe
protected void onInit(InitEvent event) {
    listBox.setItems(getListBoxItems());
}

@Supply(to = "listBox", subject = "renderer")
protected ComponentRenderer<HorizontalLayout, Simpson> listBoxRenderer() {
    return new ComponentRenderer<>(simpson -> {
        HorizontalLayout row = uiComponents.create(HorizontalLayout.class);
        row.setAlignItems(FlexComponent.Alignment.CENTER);

        Avatar avatar = uiComponents.create(Avatar.class);
        avatar.setImageHandler(getSimpsonImageHandler(simpson));

        Span name = new Span(simpson.name());
        Span shortName = new Span(simpson.shortName());
        shortName.addClassNames("short-name");

        VerticalLayout column = uiComponents.create(VerticalLayout.class);
        column.add(name, shortName);
        column.setPadding(false);
        column.setSpacing(false);

        row.add(avatar, column);
        row.addClassName("row");
        return row;
    });
}

protected List<Simpson> getListBoxItems() {
    return List.of(
            new Simpson("Homer Jay Simpson", "Homer", "homer-simpson.png"),
            new Simpson("Marjorie Jacqueline Simpson", "Marge", "marge-simpson.png"),
            new Simpson("Bartholomew Jojo Simpson", "Bart", "bart-simpson.png")
    );
}

protected DownloadHandler getSimpsonImageHandler(Simpson simpson) {
    String picture = simpson.picture();
    return DownloadHandler.forClassResource(getClass(), PATH_PREFIX + picture);
}

或者，可以使用内部的 fragmentRenderer 元素来渲染条目。有关详细信息，请参阅 Fragment 渲染器 部分。

XML 属性

下面是 listBox 的特殊属性：

名称 描述 默认值

itemsContainer

设置条目的数据容器。

—

itemsEnum

设置条目的枚举。

—

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

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - enabled - height - maxHeight - maxWidth - minHeight - minWidth - readOnly - visible - width

事件和处理器

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

名称 描述

itemEnabledProvider

确定每一项是否启用。参考 禁用条目。

itemsLabelGenerator

为每一项提供显示的文本。

renderer

为每一项提供渲染的组件。参考 条目渲染。

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

AttachEvent - ComponentValueChangeEvent - DetachEvent

XML 内部元素

一个 listBox 可以包含 fragmentRenderer 和 tooltip 作为其内部元素。

参考