GroupDataGrid 分组表格

该组件需要安装商业版分组数据网格扩展组件。

在线示例

groupDataGrid 组件是比基本的表格更强大的版本，能够进行行内分组。可以根据重复的列值将行分组成为可折叠的分组块，支持多层分组和拖动重排控制。

XML 元素	`groupDataGrid`
Java 类	`GroupDataGrid`

XML 元素

groupDataGrid

Java 类

GroupDataGrid

基本用法

在视图 XML 中声明 groupg 命名空间：

<view xmlns="http://jmix.io/schema/flowui/view"
      xmlns:groupg="http://jmix.io/schema/groupgrid/ui">

当使用顶部操作面板中的 Add Component 操作添加组件时，Studio 会自动添加该命名空间。请参见组件面板。

下面的例子中，用户按 Grade 列进行了分组：

XML 代码

<view xmlns="http://jmix.io/schema/flowui/view" xmlns:groupg="http://jmix.io/schema/groupgrid/ui"
      title="msg://basicGroupGridView.title"> (1)
    <data>
        <collection id="customersDc"
                    class="com.company.groupdatagridex1.entity.Customer"
                    fetchPlan="_base">
            <loader id="customersDl">
                <query>
                    <![CDATA[select e from Customer e]]>
                </query>
            </loader>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator auto="true"/>
    </facets>
    <layout>
        <groupg:groupDataGrid id="customersGroupDataGrid"
                              dataContainer="customersDc"
                              minWidth="100px"
                              width="100%">
            <groupg:groupBy>
                <groupg:columnRef key="grade"/> (2)
            </groupg:groupBy>
            <groupg:columns>
                <groupg:groupColumn header="Grade"/> (3)
                <groupg:column property="firstName"/>
                <groupg:column property="lastName"/>
                <groupg:column property="email"/>
                <groupg:column property="country"/>
                <groupg:column property="grade"/>
            </groupg:columns>
        </groupg:groupDataGrid>
    </layout>
</view>

1	如果组件是手动添加而不是通过 Add Component 工具箱添加，则需要声明 `groupg` 命名空间。
2	表格初始化是通过 `grade` 属性分组；也可以添加更多的分组配置。
3	添加分组列。

数据绑定

数据绑定是指将组件与数据容器进行关联。将组件绑定数据时，使用 dataContainer 属性并引用集合数据容器。请参考上面的示例。

分组项

分组项是由分组产生的特殊记录。以行的形式出现，仅包含分组表头。

为了渲染分组项，数据绑定层会创建一个临时的空实体或 DTO 实例。该实例不会添加到集合容器中，仅在分组时存在于内存中。

隐藏分组项计数

默认情况下，分组项显示分组内条目的数量。使用 groupColumn 的 displayItemCount 属性可以隐藏该数字。

多层分组

组件支持按多列分组。点击分组列的图标可以打开 Group by 对话框，然后可以添加或移除列。

排序

关于排序的配置，与 dataGrid 的配置相同。sortByGroupEnabled 属性定义排序是否影响分组顺序。

表头过滤

可以使用表头中的属性过滤器按单独的某一列过滤数据。可过滤的列会在其表头中显示一个漏斗图标（ funnel ）。点击该图标会打开过滤器对话框。

在 columns 元素上将 filterable 属性设置为 true，可为实体属性的所有列启用过滤。如需为单个列启用或禁用过滤，请在其 column 元素上设置 filterable。column 上的设置优先于 columns 上的设置：

<groupg:groupDataGrid id="customersDataGrid"
                      width="100%"
                      minHeight="20em"
                      dataContainer="customersDc">
    <groupg:groupBy>
        <groupg:columnRef key="grade"/>
    </groupg:groupBy>
    <groupg:columns filterable="true">
        <groupg:groupColumn header="Grade"/>
        <groupg:column property="firstName"/>
        <groupg:column property="lastName"/>
        <groupg:column property="email"/>
        <groupg:column property="country"/>
        <groupg:column property="grade"/>
    </groupg:columns>
</groupg:groupDataGrid>

与独立的 propertyFilter 和 genericFilter 通用过滤器组件一样，表头过滤器会将条件添加到数据加载器。在标准数据加载流程中，条件会被转换为 JPQL 并在数据库层面执行。所有过滤器的条件使用逻辑 AND 组合。

Jmix 3.1+

可以通过将 groupDataGridFilter 元素添加到 urlQueryParameters facet，将已应用的表头过滤器保留在 URL 中。

禁用分组

如需禁止用于基于特定列进行分组，可以设置该列的 groupAllowed 属性为 false。这样就不会在 Group by 对话框中显示该列。下面的示例中，不允许按 Country 列分组：

XML 代码

<groupg:groupDataGrid id="customersGroupDataGrid"
                      dataContainer="customersDc"
                      minWidth="100px"
                      width="100%">
    <groupg:groupBy>
        <groupg:columnRef key="grade"/>
    </groupg:groupBy>
    <groupg:columns>
        <groupg:groupColumn header="Grade"/>
        <groupg:column property="firstName"/>
        <groupg:column property="lastName"/>
        <groupg:column property="email"/>
        <groupg:column property="country" groupAllowed="false"/>
        <groupg:column property="grade"/>
    </groupg:columns>
</groupg:groupDataGrid>

如需禁止终端用户使用分组功能，设置 groupColumn 元素的 displayColumnsGrouperOnIconClick="false"。

默认的分组仍然可以通过 groupBy 元素声明或 groupBy() 方法编程式设置。

自定义分组列

如需使用自定义分组值，在视图控制器中添加新的分组属性描述。以下示例引入了一个将名字和姓氏结合的新分组属性。

这种合成属性不会自动排序。为了让排序机制也能正常，可以在分组属性描述符中使用 .withSortProperties(…) 指定排序属性。

XML 代码

<groupg:groupDataGrid id="customersGroupDataGrid"
                      dataContainer="customersDc"
                      minWidth="100px"
                      width="100%">
    <groupg:columns>
        <groupg:groupColumn key="group" header="Full name"/> <!-- 1 -->
        <groupg:column key="fullName" header="Full name"/>
        <groupg:column property="email"/>
        <groupg:column property="country"/>
        <groupg:column property="grade"/>
    </groupg:columns>
</groupg:groupDataGrid>

Java 代码

@ViewComponent
private GroupDataGrid<Customer> customersGroupDataGrid;

@Subscribe
public void onInit(InitEvent event) {
    GroupDataGridItems<Customer> items = customersGroupDataGrid.getItems();

    if (items != null) {
        items.addGroupPropertyDescriptor( (1)
                new BaseGroupPropertyDescriptor<Customer>("fullName",
                        context -> context.getItem().getFirstName() + " " + context.getItem().getLastName())
                        .withSortProperties(List.of("firstName", "lastName"))); (2)

        customersGroupDataGrid.groupByKeys("fullName"); (3)
    }
}
@Supply(to = "customersGroupDataGrid.fullName", subject = "renderer") (4)
protected Renderer<Customer> supplyRendererToFullNameColumn() {
    return new TextRenderer<>(item -> item.getFirstName() + " " + item.getLastName());
}

1	描述一个新的分组属性，由 `firstName` 和 `lastName` 拼接而成。
2	`.withSortProperties(List.of("firstName", "lastName"))` 告诉组件如何对合成属性排序。
3	默认按 `fullName` 分组。
4	为“全名”列提供一个渲染回调，可以在不分组时显示内容。否则，不分组时列显示为空。

导出 Excel

导出功能由免费的表格导出操作扩展组件提供，该扩展组件支持所有表格类型：groupDataGrid、dataGrid 和 treeDataGrid。

该扩展组件提供三种导出选项。有不同的导出范围以及生成 Excel 的格式：

All Rows – 导出所有行并展平分组。
Current Page – 仅导出当前可见行，同时 保留表格中显示的分组结构。
Selected Rows – 导出当前选中的行并展平分组。

样式

主题

在线示例

不同的样式版本可以通过 themeNames 属性配置。多个主题可以同时使用，样式版本与 dataGrid 数据网格一样。

分组标签

组件中折叠的分组组显示 +，展开的分组显示 -。如需自定义图标，可以将图标添加到应用程序样式中。把默认的 content 值替换为所需的图标字符代码（例如，使用 Vaadin 字体图标集合中的 e7c1 和 e7bf）：

application.css

vaadin-grid-tree-toggle.jmix-group-toggle {
    &::part(toggle)::before {
        content: "\e7c1";
    }

    &[expanded]::part(toggle)::before {
        content: "\e7bf";
    }
}

参考组件的可样式化 parts。

分组列图标

分组列图标可通过 groupColumn 元素的 groupIcon 属性进行自定义。如需隐藏图标，将 groupIconVisible 设置为 false。

XML 属性

下面是 groupDataGrid 的特殊属性：

名称	描述	默认值
`aggregatable`	如果为 `true`，则启用列的聚合。参阅聚合。	`false`
`columnReorderingAllowed`	如果为 `true`，则允许用户更改列的顺序。	`false`
`emptyStateText`	表格为空时显示的文本。使用 null 可移除当前的空状态内容。参阅空状态。	–
`selectionMode`	设置选择模式。支持：`SINGLE`、`MULTI`。	`SINGLE`
`aggregationPosition`	如果组件中的数据是可聚合的，则决定聚合行显示在其他行的上方还是下方。支持：`TOP` 或 `BOTTOM`。参阅聚合。	`BOTTOM`
`allRowsVisible`	如果为 `true`，表格将一次显示所有行且不显示滚动条，从而有效禁用虚拟滚动。即表格会同时在 DOM 中渲染所有行，而不是仅渲染可见行并在用户滚动时加载更多行。不建议在条目数量较大时使用此功能，因为可能会导致性能问题。	–
`columnRendering`	设置列渲染模式。在 `EAGER` 模式下，所有列都会预先渲染，无论其在视窗内是否可见。在 `LAZY` 模式下，仅当相应列位于可见视窗内时才渲染主体单元格。	`EAGER`
`detailsVisibleOnClick`	如果为 `true`，则支持通过鼠标单击显示条目详情。	`true`
`dropMode`	确定可以进行拖放的行。可选值：`BETWEEN`、`ON_TOP`、`ON_TOP_OR_BETWEEN`、`ON_GRID`。此特性可用于例如重新排序行以及在网格之间拖拽行。	–
`editorBuffered`	如果为 `true`，则为内联编辑启用缓存模式，即用户必须通过点击确认按钮来确认所做的更改。此模式还支持用户取消更改。在非缓存模式下，更改无需确认即可生效。	`false`
`multiSort`	如果为 `true`，则启用按多列排序。	`false`
`multiSortOnShiftClickOnly`	如果为 `true`，则仅当按住 Shift 键点击列标题时才激活多列排序。	`false`
`multiSortPriority`	设置被点击的列是添加到已排序列列表的末尾还是开头。可选值：`PREPEND`、`APPEND`。	`PREPEND`
`nestedNullBehavior`	设置当解析嵌套属性时（属性链中可能包含 null 值）的行为。可选值：`THROW`、`ALLOW_NULLS`。	`THROW`
`pageSize`	设置页面大小，即一次从数据提供者获取的条目数量。	`50`
`rowsDraggable`	如果为 `true`，则允许用户在网格中拖拽行。	`false`
`sortByGroupEnabled`	如果为 `true`：为分组列启用排序。按其他列排序会在每个分组内重新排列行，但初始分组顺序保持不变。如果为 `false`：为分组列禁用排序。按其他列排序会相应地重新排列分组顺序。	`true`

名称

描述

默认值

aggregatable

如果为 true，则启用列的聚合。参阅聚合。

false

columnReorderingAllowed

如果为 true，则允许用户更改列的顺序。

false

emptyStateText

表格为空时显示的文本。使用 null 可移除当前的空状态内容。参阅空状态。

–

selectionMode

设置选择模式。支持：SINGLE、MULTI。

SINGLE

aggregationPosition

如果组件中的数据是可聚合的，则决定聚合行显示在其他行的上方还是下方。支持：TOP 或 BOTTOM。参阅聚合。

BOTTOM

allRowsVisible

如果为 true，表格将一次显示所有行且不显示滚动条，从而有效禁用虚拟滚动。即表格会同时在 DOM 中渲染所有行，而不是仅渲染可见行并在用户滚动时加载更多行。

不建议在条目数量较大时使用此功能，因为可能会导致性能问题。

–

columnRendering

设置列渲染模式。在 EAGER 模式下，所有列都会预先渲染，无论其在视窗内是否可见。在 LAZY 模式下，仅当相应列位于可见视窗内时才渲染主体单元格。

EAGER

detailsVisibleOnClick

如果为 true，则支持通过鼠标单击显示条目详情。

true

dropMode

确定可以进行拖放的行。可选值：BETWEEN、ON_TOP、ON_TOP_OR_BETWEEN、ON_GRID。此特性可用于例如重新排序行以及在网格之间拖拽行。

–

editorBuffered

如果为 true，则为内联编辑启用缓存模式，即用户必须通过点击确认按钮来确认所做的更改。此模式还支持用户取消更改。在非缓存模式下，更改无需确认即可生效。

false

multiSort

如果为 true，则启用按多列排序。

false

multiSortOnShiftClickOnly

如果为 true，则仅当按住 Shift 键点击列标题时才激活多列排序。

false

multiSortPriority

设置被点击的列是添加到已排序列列表的末尾还是开头。可选值：PREPEND、APPEND。

PREPEND

nestedNullBehavior

设置当解析嵌套属性时（属性链中可能包含 null 值）的行为。可选值：THROW、ALLOW_NULLS。

THROW

pageSize

设置页面大小，即一次从数据提供者获取的条目数量。

50

rowsDraggable

如果为 true，则允许用户在网格中拖拽行。

false

sortByGroupEnabled

如果为 true：

为分组列启用排序。
按其他列排序会在每个分组内重新排列行，但初始分组顺序保持不变。

如果为 false：

为分组列禁用排序。
按其他列排序会相应地重新排列分组顺序。

true

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

id - alignSelf - ariaLabel - classNames - colspan - css - dataContainer - enabled - focusShortcut - height - justifySelf - maxHeight - maxWidth - metaClass - minHeight - minWidth - tabIndex - themeNames - visible - width

事件和处理器

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

在 Jmix Studio 生成处理器桩代码时，可以使用 Jmix UI 组件面板的 Handlers 标签页或者视图类顶部面板的 Generate Handler 添加，也可以通过 Code → Generate 菜单（Alt+Insert / Cmd+N）生成。

名称描述

名称	描述
`CellFocusEvent`	`com.vaadin.flow.component.grid.CellFocusEvent` 当表格中的单元格获得焦点时触发。对应 `grid-cell-focus` DOM 事件。
`CollapseEvent`	当分组折叠时触发。
`ColumnReorderEvent`	`com.vaadin.flow.component.grid.ColumnReorderEvent` 当表格中发生列重排时触发。对应 `column-reorder-all-columns` DOM 事件。
`ColumnResizeEvent`	`com.vaadin.flow.component.grid.ColumnResizeEvent` 当用户调整表格列的大小时触发。对应 `column-drag-resize` DOM 事件。
`ExpandEvent`	当分组展开时触发。
`GridDragEndEvent`	`com.vaadin.flow.component.grid.dnd.GridDragEndEvent` - 表格中行的拖拽结束事件。对应 `grid-dragend` DOM 事件。
`GridDragStartEvent`	`com.vaadin.flow.component.grid.dnd.GridDragStartEvent` - 表格中行的拖拽开始事件。对应 `grid-dragstart` DOM 事件。
`GridDropEvent`	`com.vaadin.flow.component.grid.dnd.GridDropEvent` - 发生在表格或其行上的放置事件。对应 `grid-drop` DOM 事件。
`GroupItemClickEvent`	当单击分组项内的行时触发。
`GroupItemDoubleClickEvent`	当双击分组项内的行时触发。
`GroupingChangedEvent`	当分组发生变化（添加或移除列）时触发。
`ItemClickEvent`	`com.vaadin.flow.component.grid.ItemClickEvent` 当单击表格项时触发。对应 `item-click` DOM 事件。
`ItemDoubleClickEvent`	`com.vaadin.flow.component.grid.ItemDoubleClickEvent` 当双击表格项时触发。对应 `item-double-click` DOM 事件。
`SelectionEvent`	选择事件，统一了多选和单选事件（在只需要单个选中条目的情况下）。
`SortEvent`	`com.vaadin.flow.data.event.SortEvent` - 描述 DataProvider 排序发生变化的事件。由 `SortNotifiers` 触发。
`dataGenerator`	为表格添加数据生成器。如果该生成器已添加，则不执行任何操作。参考 `com.vaadin.flow.data.provider.HasDataGenerators` 接口。
`dragFilter`	允许控制哪些特定行可以被拖拽，而不是通过 rowsDraggable 使所有行都可拖拽。
`dropFilter`	允许控制哪些特定行是有效的放置目标。
`enterPressHandler`	处理用户按下 Enter 键时的事件。
`groupPartNameGenerator`	根据给定条件为分组项生成 CSS 类名的 parts。支持自定义分组项。
`groupTooltipGenerator`	根据给定条件为分组生成 tooltip。
`itemSelectableProvider`	设置一个判断，用于检查表格中的特定项是否可由用户选择或取消选择。该方法接收一个条目实例，如果用户可以更改该条目的选择状态则返回 `true`，否则返回 `false`。
`partNameGenerator`	根据给定条件为单元格生成 CSS 类名的 parts。支持根据所显示的数据自定义单元格外观。
`sortBuilderDelegate`	从 `GroupDataGridSortContext` 构建一个 `DataGridSort` 对象，支持组件特定的映射规则，将列与自定义的比较器和数据库排序表达式对应。参考排序构建器委托。
`tooltipGenerator`	根据给定条件为列单元格生成 tooltip。参考在线演示。

CellFocusEvent

com.vaadin.flow.component.grid.CellFocusEvent 当表格中的单元格获得焦点时触发。对应 grid-cell-focus DOM 事件。

CollapseEvent

当分组折叠时触发。

ColumnReorderEvent

com.vaadin.flow.component.grid.ColumnReorderEvent 当表格中发生列重排时触发。对应 column-reorder-all-columns DOM 事件。

ColumnResizeEvent

com.vaadin.flow.component.grid.ColumnResizeEvent 当用户调整表格列的大小时触发。对应 column-drag-resize DOM 事件。

ExpandEvent

当分组展开时触发。

GridDragEndEvent

com.vaadin.flow.component.grid.dnd.GridDragEndEvent - 表格中行的拖拽结束事件。对应 grid-dragend DOM 事件。

GridDragStartEvent

com.vaadin.flow.component.grid.dnd.GridDragStartEvent - 表格中行的拖拽开始事件。对应 grid-dragstart DOM 事件。

GridDropEvent

com.vaadin.flow.component.grid.dnd.GridDropEvent - 发生在表格或其行上的放置事件。对应 grid-drop DOM 事件。

GroupItemClickEvent

当单击分组项内的行时触发。

GroupItemDoubleClickEvent

当双击分组项内的行时触发。

GroupingChangedEvent

当分组发生变化（添加或移除列）时触发。

ItemClickEvent

com.vaadin.flow.component.grid.ItemClickEvent 当单击表格项时触发。对应 item-click DOM 事件。

ItemDoubleClickEvent

com.vaadin.flow.component.grid.ItemDoubleClickEvent 当双击表格项时触发。对应 item-double-click DOM 事件。

SelectionEvent

选择事件，统一了多选和单选事件（在只需要单个选中条目的情况下）。

SortEvent

com.vaadin.flow.data.event.SortEvent - 描述 DataProvider 排序发生变化的事件。由 SortNotifiers 触发。

dataGenerator

为表格添加数据生成器。如果该生成器已添加，则不执行任何操作。参考 com.vaadin.flow.data.provider.HasDataGenerators 接口。

dragFilter

允许控制哪些特定行可以被拖拽，而不是通过 rowsDraggable 使所有行都可拖拽。

dropFilter

允许控制哪些特定行是有效的放置目标。

enterPressHandler

处理用户按下 Enter 键时的事件。

groupPartNameGenerator

根据给定条件为分组项生成 CSS 类名的 parts。支持自定义分组项。

groupTooltipGenerator

根据给定条件为分组生成 tooltip。

itemSelectableProvider

设置一个判断，用于检查表格中的特定项是否可由用户选择或取消选择。该方法接收一个条目实例，如果用户可以更改该条目的选择状态则返回 true，否则返回 false。

partNameGenerator

根据给定条件为单元格生成 CSS 类名的 parts。支持根据所显示的数据自定义单元格外观。

sortBuilderDelegate

从 GroupDataGridSortContext 构建一个 DataGridSort 对象，支持组件特定的映射规则，将列与自定义的比较器和数据库排序表达式对应。参考排序构建器委托。

tooltipGenerator

根据给定条件为列单元格生成 tooltip。参考在线演示。

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

AttachEvent - BlurEvent - DetachEvent - FocusEvent

XML 内部元素

一个 groupDataGrid 可以包含 actions, groupBy、columns、contextMenu 和 emptyStateComponent 作为其直接内部元素。一个 columns 可以包含 column、groupColumn 和 editorActionsColumn。与数据网格同样的属性参考 actions、contextMenu 和 emptyStateComponent。

如需为选中的元素添加内部元素，点击 Jmix UI 属性面板中的 Add 按钮。

groupBy

groupBy 元素包含一个或多个 columnRef 元素，指定哪些列用于分组。

columnRef

columnRef 元素定义用作分组的列。其 key 属性必须与 column 中声明的 key 属性一致。

columns

columns 元素包含 column 元素，并且定义这些列的共享属性。支持 includeAll、exclude、sortable、resizable 和 filterable，参考数据网格的 columns。

column

column 元素声明单独的一列。为单独的列设置属性会覆盖 columns 上的设置。支持数据网格 column 的配置，并添加了 groupAllowed 属性，用于设置是否允许对改列进行分组。

groupColumn

groupColumn 元素声明用于分组的列，以及该列相对于其他列的位置。key 属性为必需。可以包含一个内部的 groupIcon 元素用于提供自定义图标组件。

名称描述默认值

名称	描述	默认值
`autoHidden`	设置当没有分组属性时是否自动隐藏分组列。	—
`autoWidth`	设置列宽是否根据其内容计算。	—
`displayColumnsGrouperOnIconClick`	设置点击分组图标是否打开 Group by 对话框。	—
`displayItemsCount`	设置分组标题是否显示子条目的数量。请参见隐藏分组项计数。	—
`flexGrow`	设置该列相对于其他列的延展量。	—
`footer`	设置列 footer 文本。	—
`frozen`	将列锁定在网格的起始边缘。	—
`frozenToEnd`	将列锁定在网格的末尾边缘。	—
`groupIcon`	使用 Vaadin 图标名称设置分组图标。当需要图标组件时，使用内部的 `groupIcon` 元素。	—
`groupIconVisible`	设置分组图标是否可见。	—
`header`	设置列 header 文本。	—
`key`	设置用于标识分组列的列键值。	—
`resizable`	设置用户是否可以调整列大小。	—
`sortable`	设置用户是否可以按分组列排序。	—
`visible`	设置列是否可见。	—
`width`	以 CSS 字符串设置列宽，使用 `px`、`%`、`rem` 或 `em` 等单位。对于字体相对宽度，优先使用 `rem` 而不是 `em`，因为 header、内容和 footer 字体大小的差异可能导致错位。	—

autoHidden

设置当没有分组属性时是否自动隐藏分组列。

—

autoWidth

设置列宽是否根据其内容计算。

—

displayColumnsGrouperOnIconClick

设置点击分组图标是否打开 Group by 对话框。

—

displayItemsCount

设置分组标题是否显示子条目的数量。请参见隐藏分组项计数。

—

flexGrow

设置该列相对于其他列的延展量。

—

footer

设置列 footer 文本。

—

frozen

将列锁定在网格的起始边缘。

—

frozenToEnd

将列锁定在网格的末尾边缘。

—

groupIcon

使用 Vaadin 图标名称设置分组图标。当需要图标组件时，使用内部的 groupIcon 元素。

—

groupIconVisible

设置分组图标是否可见。

—

header

设置列 header 文本。

—

key

设置用于标识分组列的列键值。

—

resizable

设置用户是否可以调整列大小。

—

sortable

设置用户是否可以按分组列排序。

—

visible

设置列是否可见。

—

width

以 CSS 字符串设置列宽，使用 px、%、rem 或 em 等单位。对于字体相对宽度，优先使用 rem 而不是 em，因为 header、内容和 footer 字体大小的差异可能导致错位。

—

本页是否有帮助？

感谢您的反馈

出错啦~