分组表格 - CUBA 框架开发者手册

3.5.2.1.20. 分组表格

GroupTable 分组表格能动态支持按任意字段把数据分组。如果需要基于某列分组，则把该列拖拽到 gui_groupTableIcon 元素的左侧。被分组的数据可以通过 gui_groupBox_plus / gui_groupBox_minus 按钮展开/收起。

该组件对应的 XML 名称为: groupTable。

必须为 GroupTable 分组表格定义 CollectionContainer 类型的数据容器。否则，分组功能不可用。示例：

<data>
    <collection id="ordersDc"
                class="com.company.sales.entity.Order"
                view="order-with-customer">
        <loader id="ordersDl">
            <query>
                <![CDATA[select e from sales_Order e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <groupTable id="ordersTable"
                width="100%"
                dataContainer="ordersDc">
        <columns>
            <group>
                <column id="date"/>
            </group>
            <column id="customer"/>
            <column id="amount"/>
        </columns>
        <rowsCount/>
    </groupTable>
</layout>

group 是 columns 中的可选元素，它包含若干列 column，打开对应界面时，会默认将数据按这些列进行分组。

下面的例子中，我们会使用 columns 元素的 includeAll 属性，以及 group 元素。

<groupTable id="groupTable"
            width="100%"
            height="100%"
            dataContainer="customersDc">
    <columns includeAll="true">
        <group>
            <column id="address"/>
        </group>
        <column id="name"
                sortable="false"/>
    </columns>
</groupTable>

结果是给 name 列设置了一个特殊的属性，并且 GroupTable 按照 address 列做了分组。

可以针对每个列 column 设置 groupAllowed 布尔值属性，控制该列是否可以用来分组数据。

如果 aggregatable 属性设置为 true, 则会针对每组显示聚合结果；并在第一行显示针对所有行的聚合结果。如果 showTotalAggregation 属性设置为 false, 针对所有行的聚合结果则不会显示。

如果 multiselect 多选属性设置为 true, 按下 Ctrl 键并单击分组行时，该组会展开，该组的所有行都会被选上。但反过来不同，如果整组都被选上，Ctrl+单击 并不会反选所有组数据。通过 Ctrl 还是可以反选特定的行。

GroupTable 分组表格接口的方法:

groupByColumns() - 基于给定列进行分组。

以下示例中，会将数据先以 department 分组，再以 city 分组:
```
groupTable.groupByColumns("department", "city");
```

ungroupByColumns() - 取消基于给定列的分组。

以下示例中，会取消针对 department 的分组, 但基于 city 的分组会保留。
```
groupTable.ungroupByColumns("department");
```

ungroup() - 取消所有分组。

setAggregationDistributionProvider() 方法与 Table 组件的同名方法类似，不同之处在于，当创建 provider 时，会使用 GroupAggregationDistributionContext<V> 对象，包含了附加的信息：
- GroupInfo groupInfo – 带有分组行信息的对象：分组的所有列的属性及其值。

getAggregationResults() 方法会为特定的 GroupInfo 对象返回一个聚合值的映射（map），键值为表格列的标识符，值为聚合值。

setStyleProvider() 方法可以为单元格设置显示样式。对于 GroupTable，该方法接收继承自 Table.StyleProvider 的 GroupTable.GroupStyleProvider。

GroupStyleProvider 有个特殊方法，用来为分组行设置样式，该方法使用 GroupInfo 参数。GroupTable 会为每个分组行调用此方法。

示例：

@Inject
private GroupTable<Customer> customerTable;

@Subscribe
public void onInit(InitEvent event) {
    customerTable.setStyleProvider(new GroupTable.GroupStyleProvider<Customer>() {

        @SuppressWarnings("unchecked")
        @Override
        public String getStyleName(GroupInfo info) {
            CustomerGrade grade = (CustomerGrade) info.getPropertyValue(info.getProperty());
            switch (grade) {
                case PREMIUM:
                    return "premium-grade";
                case HIGH:
                    return "high-grade";
                case STANDARD:
                    return "standard-grade";
            }
            return null;
        }

        @Override
        public String getStyleName(Customer customer, @Nullable String property) {
            if (Boolean.TRUE.equals(customer.getActive())) {
                return "active-customer";
            }
            return null;
        }
    });
}

然后，需要在应用程序主题中定义代码中用到的这组样式。创建主题的详细内容请参阅 Themes。对于 web 客户端，新的样式在 styles.scss 文件定义。控制器中定义的 style name，会变成 CSS 选择器。示例：

.active-customer {
    font-weight: bold;
}

.premium-grade {
    background-color: red;
    color: white;
}

.high-grade {
    background-color: green;
    color: white;
}

.standard-grade {
    background-color: blue;
    color: white;
}

GroupTable 分组表格的其它功能类似于普通表格.

GroupTable 的属性列表: align - aggregatable - aggregationStyle - caption - captionAsHtml - columnControlVisible - contextHelpText - contextHelpTextHtmlEnabled - contextMenuEnabled - css - dataContainer - description - descriptionAsHtml - editable - emptyStateLinkMessage - emptyStateMessage - enable - box.expandRatio - height - htmlSanitizerEnabled - id - metaClass - multiLineCells - multiselect - presentations - reorderingAllowed - settingsEnabled - showTotalAggregation - sortable - stylename - tabIndex - textSelectionEnabled - visible - width
GroupTable 的元素: actions - buttonsPanel - columns - rows - rowsCount
columns的属性: includeAll - exclude
columns的元素: column - group
column 列属性列表: align - caption - captionProperty - collapsed - dateFormat - editable - expandRatio - groupAllowed - id - link - linkInvoke - linkScreen - linkScreenOpenType - maxTextLength - optionsContainer - resolution - sort - sortable - visible - width
column 列的元素: aggregation - formatter
aggregation 的属性: editable - strategyClass - type - valueDescription
API: addColumnCollapseListener - addSelectionListener - getAggregationResults - groupByColumns - setAggregationDistributionProvider - setClickListener - setEmptyStateLinkClickHandler - setItemDescriptionProvider - setStyleProvider - ungroup - ungroupByColumns