radioButtonGroup 单选组

radioButtonGroup 支持使用单选按钮从选项列表中选择单个值。

XML 元素

radioButtonGroup

Java 类

JmixRadioButtonGroup

基本用法

在线示例

radioButtonGroup 的最基本用法是为实体属性选择一个枚举值。

<radioButtonGroup id="verticalRadioButtonGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<radioButtonGroup id="horizontalRadioButtonGroup"
               label="Horizontal"
               themeNames="horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

上面的示例中，User 实体的 onboardingStatus 属性是一个 OnboardingStatus 枚举类型。

从数据容器获取选项

在线示例

radioButtonGroup 可以通过 itemsContainer 属性设置的数据容器获取选项列表。示例：

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

这里 radioButtonGroup 会显示 Hobby 实体的实例名，该实体位于 hobbiesDc 数据容器内，通过 getValue() 方法返回当前选择的实体实例。

选项的构建

在线示例

可以通过下列方法为 radioButtonGroup 设置选项列表：

从列表获取选项

<radioButtonGroup id="radioButtonGroupWithList"
                  label="Items List"
                  themeNames="vertical"/>

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

@ViewComponent
protected JmixRadioButtonGroup<Integer> radioButtonGroupWithList;
    radioButtonGroupWithList.setItems(getItemsList());
protected List<Integer> getItemsList() {
    return List.of(2, 4, 5, 7);
}

自定义选项名称

<radioButtonGroup id="radioButtonGroupWithMap"
                  label="Items Map"
                  themeNames="vertical"/>

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

@ViewComponent
protected JmixRadioButtonGroup<Integer> radioButtonGroupWithMap;
    ComponentUtils.setItemsMap(radioButtonGroupWithMap, getItemsMap());
protected Map<Integer, String> getItemsMap() {
    Map<Integer, String> itemsMap = new LinkedHashMap<>();
    itemsMap.put(2, "Two");
    itemsMap.put(4, "Four");
    itemsMap.put(5, "Five");
    itemsMap.put(7, "Seven");
    return itemsMap;
}

从枚举获取选项

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

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

<radioButtonGroup id="radioButtonGroupWithEnum"
                  label="Items Enum"
                  themeNames="vertical"/>

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

@ViewComponent
protected JmixRadioButtonGroup<CustomerGrade> radioButtonGroupWithEnum;
    radioButtonGroupWithEnum.setItems(CustomerGrade.class);

选项启用

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

@Install(to = "radioButtonGroup", subject = "itemEnabledProvider")
private boolean radioButtonGroupItemEnabledProvider(OnboardingStatus onboardingStatus) {
    if (onboardingStatus != null) {
        return onboardingStatus.getId() != 30;
    }
    return true;
}

自定义选项标签

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

@Install(to = "statusRadioButtonGroup", subject = "itemLabelGenerator")
private String statusRadioButtonGroupItemLabelGenerator(
        final OnboardingStatus t) {
    return metadataTools.format(t).toUpperCase();
}

选项渲染

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

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

@Autowired
private UiComponents uiComponents;

@Autowired
private FileStorage fileStorage;

@Supply(to = "rbgRenderer", subject = "renderer")
private ComponentRenderer<HorizontalLayout, User> rbgRendererRenderer() {
    return new ComponentRenderer<>(user -> {
        FileRef fileRef = user.getPicture();
        HorizontalLayout row = uiComponents.create(HorizontalLayout.class);
        row.setAlignItems(FlexComponent.Alignment.END);
        if (fileRef != null) {
            Image image = uiComponents.create(Image.class);
            image.setWidth("30px");
            image.setHeight("30px");
            image.setClassName("user-picture");
            InputStreamDownloadHandler handler =
                    DownloadHandler.fromInputStream(event ->
                            new DownloadResponse(
                                    fileStorage.openStream(fileRef),
                                    fileRef.getFileName(),
                                    fileRef.getContentType(),
                                    -1
                            ));
            image.setSrc(handler);
            row.add(image);
        }
        row.add(new Span(user.getFirstName() + ", " + user.getLastName()));
        return row;
    });
}

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

样式版本

在线示例

使用 themeNames 属性配置一个或多个样式。

样式 描述 支持的主题

vertical

内容垂直排布

Lumo

helper-above-field

帮助文字显示在字段上方，标题下方。

Aura, Lumo

XML 属性

下面是 radioButtonGroup 的特殊属性：

名称 描述 默认值

itemsContainer

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

—

itemsEnum

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

—

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

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - dataContainer - datatype - enabled - errorMessage - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - readOnly - required - requiredMessage - themeNames - visible - width

事件和处理器

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

名称 描述

itemEnabledProvider

itemEnabledProvider 会应用在每个选项上，以确定选项是启用（true）还是禁用（false）。参阅 选项启用。

itemLabelGenerator

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

renderer

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

validator

验证组件值。

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

AttachEvent - ClientValidatedEvent - ComponentValueChangeEvent - DetachEvent - statusChangeHandler

XML 内部元素

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

参考