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 描述或者 Component Hierarchy 面板选中该组件,然后用 Component Inspector 面板的 Handlers 标签页生成。

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

ContextHelpIconClickHandler

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 属性

CheckBoxGroup XML 元素