CheckBoxGroup 复选框组

在线示例

CheckBoxGroup - 复选框组 允许用户使用复选框从选项列表中选择多个值。如果仅需从列表中选取一个值，可以使用 RadioButtonGroup 组件。

组件的 XML 名称：checkBoxGroup。

check box group operations

基本用法

该组件可以从数据容器中获取一组选项。需使用 optionsContainer 属性，示例：

<data>
    <collection id="countriesDc" class="ui.ex1.entity.Country">
        <fetchPlan extends="_local"/>
        <loader id="countriesDl">
            <query>
                <![CDATA[select e from uiex1_Country e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <checkBoxGroup optionsContainer="countriesDc"
                   caption="Countries"/>
</layout>

这个例子中，CheckBoxGroup 组件会展示 Country 实体的 实例名称，实体位于 countriesDc 数据容器中，容器的 getValue() 方法返回所有选中实体的集合。

countries check box group

另外，也可以通过编程的方式实现：

<data>
    <collection id="countriesDc" class="ui.ex1.entity.Country">
        <fetchPlan extends="_local"/>
        <loader id="countriesDl">
            <query>
                <![CDATA[select e from uiex1_Country e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <checkBoxGroup id="countriesCheckBoxGroup"
                   caption="Countries"/>
</layout>

请注意，上面这段 XML 与之前的区别是，这里我们没有给 countriesCheckBoxGroup 设置 optionsContainer，因为要在控制器编码实现：

@Autowired
private CheckBoxGroup<Country> countriesCheckBoxGroup;
@Autowired
private CollectionContainer<Country> countriesDc;

@Subscribe
protected void onInit(InitEvent event) {
    countriesCheckBoxGroup.setOptions(new ContainerOptions<>(countriesDc));
}

使用 captionProperty 属性，可以选择另一个实体属性在组件内展示。

orientation 属性定义组内元素的排列方式。默认情况下，元素垂直排列。设置为 horizontal 时，水平排列。

选项

setOptions()

setOptions() 方法接收一个实现了 Options 接口的类作为参数，可以使用类中定义的所有选项：

@Autowired
private CheckBoxGroup<Operation> checkBoxGroup;

@Subscribe
protected void onInit(InitEvent event) {
    checkBoxGroup.setOptions(new EnumOptions<>(Operation.class));
}

setOptionsEnum()、setOptionsList() 和 setOptionsMap() 与 ComboBox 组件中的用法相同。

验证

如需验证 CheckBoxGroup 组件中输入的值，可以用内部的 validator 元素。

CheckBoxGroup 有下列预定义的验证器：

下面例子中，我们演示如何在 validatedCheckBoxGroup 内使用 SizeValidator：

<checkBoxGroup id="validatedCheckBoxGroup"
               optionsContainer="customersDc"
               caption="The number of customers is limited from 2 to 5">
    <validators>
        <size min="2" max="5"/>
    </validators>
</checkBoxGroup>

事件和处理器

如需使用 Jmix Studio 生成处理器的桩代码，需要在界面 XML 描述或者 Jmix UI 层级结构面板选中该组件，然后用 Jmix UI 组件面板的 Handlers 标签页生成。

或者可以使用界面控制器顶部面板的 Generate Handler 按钮。

ContextHelpIconClickHandler

参阅 ContextHelpIconClickHandler。

OptionCaptionProvider

参阅 OptionCaptionProvider。

OptionDescriptionProvider

选项描述提供器会为 CheckBoxGroup 组件的选项生成提示信息。

下面例子中，我们演示 checkBoxGroupDesc 如何使用 OptionDescriptionProvider：

@Install(to = "checkBoxGroupDesc", subject = "optionDescriptionProvider")
protected String checkBoxGroupDescOptionDescriptionProvider(Customer customer) {
    return "Email: " + customer.getEmail();
}

如需以编程方式注册描述提供器，用组件的 setOptionDescriptionProvider() 方法。

OptionIconProvider

参阅 OptionIconProvider。

Validator

为组件添加 validator 实例。如果值验证失败，validator 必须抛出 ValidationException 异常。

如果 预定义 的验证器不能满足要求，可以添加自定义的验证器实例：

@Install(to = "validCheckBoxGroup", subject = "validator")
protected void validCheckBoxGroupValidator(Collection<EducationalStage> value) {
    if (value.contains(EducationalStage.NO) & value.size() > 1)
        throw new ValidationException("You cannot select the No Education " +
                "value together with other values");
}

ValueChangeEvent

请参阅 ValueChangeEvent。

CheckBoxGroup XML 属性

可以使用 Studio 界面设计器的 Jmix UI 组件面板查看和编辑组件的属性。

align - caption - captionAsHtml - captionProperty - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - optionsContainer - optionsEnum - orientation - property - required - requiredMessage - responsive - rowspan - stylename - tabIndex - visible - width

CheckBoxGroup XML 元素

validators