checkboxGroup 复选框组

checkboxGroup 支持用户从复选框组中选择多个值。

XML 元素

checkboxGroup

Java 类

JmixCheckboxGroup

基本用法

在线示例

下面的示例用一个枚举设置了两个 checkboxGroup 的选项，分别以垂直和水平显示。

<checkboxGroup id="verticalCheckboxGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<checkboxGroup id="horizontalCheckboxGroup"
               label="Horizontal"
               themeNames="horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

数据感知的 checkboxGroup

该组件支持绑定至 data container 中的实体属性。

如需将 checkBoxGroup 绑定至实体属性：

  1. 使用 dataContainer 属性指定数据容器的名称。

  2. 使用 property 属性指定实体属性的名称。

<data>
    <instance class="com.company.onboarding.entity.User" id="userDc">
        <fetchPlan extends="_base">
            <property name="hobbies" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="userDl"/>
    </instance>
    <collection class="com.company.onboarding.entity.Hobby" id="hobbiesDc">
        <fetchPlan extends="_base"/>
        <loader id="hobbiesDl">
            <query>
                <![CDATA[select e from Hobby e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <checkboxGroup dataContainer="userDc"
                   property="hobbies"
                   itemsContainer="hobbiesDc"
                   id="checkboxGroup"/>
</layout>

示例中，checkBoxGroup 会展示 Hobby 实体的实例名，getTypedValue() 方法返回选择实例的 Collection.

自定义选项

在线示例

使用下列方法可以为 checkBoxGroup 设置选项：

选项列表

setItems() 方法可以编程式设置组件的选项。

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

选项映射

ComponentUtils.setItemsMap() 支持分别设置每个选项的显示名称和值。

@ViewComponent
protected JmixCheckboxGroup<Integer> checkboxGroupWithMap;
    ComponentUtils.setItemsMap(checkboxGroupWithMap, 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;
}

枚举选项

在线示例

checkBoxGroup 的选项值还可以通过声明式或编程的方式设置为枚举。

下面的示例演示了声明式用法。

<checkboxGroup id="verticalCheckboxGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<checkboxGroup id="horizontalCheckboxGroup"
               label="Horizontal"
               themeNames="horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

下面的示例使用了编程式用法。

@ViewComponent
protected JmixCheckboxGroup<CustomerGrade> checkboxGroupWithEnum;
    checkboxGroupWithEnum.setItems(CustomerGrade.class);

方向

在线示例

使用 themeNames 可以显式控制内容的排列：

<checkboxGroup id="verticalCheckboxGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<checkboxGroup id="horizontalCheckboxGroup"
               label="Horizontal"
               themeNames="horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

自定义选项展示

组件支持对选项进行自定义展示，通过 setRenderer() 方法或 @Supply 注解。

@Autowired
private UiComponents uiComponents;
@Autowired
private FileStorage fileStorage;

@Supply(to = "userCheckboxGroup", subject = "renderer")
private ComponentRenderer<HorizontalLayout, User> userCheckboxGroupRenderer() {
    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 XML 元素进行渲染。参考 Fragment 渲染器。

样式版本

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

样式 描述 支持的主题

vertical

内容垂直排布

Lumo

horizontal

内容水平排布

Aura

helper-above-field

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

Aura, Lumo

XML 属性

下面是 checkboxGroup 的特殊属性：

名称 描述 默认值

itemsContainer

设置选项数据容器。

—

itemsEnum

设置选项枚举

—

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

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

事件和处理器

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

名称 描述

itemEnabledProvider

控制每个选项是否启用。

itemLabelGenerator

为每个选项提供文本显示。

renderer

为每个选项提供渲染的组件。参考 自定义选项展示。

validator

验证组件值。

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

AttachEvent - ClientValidatedEvent - ComponentValueChangeEvent - DetachEvent - TypedValueChangeEvent - statusChangeHandler

XML 内部元素

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

参考