groupDataGrid

Для работы компонента требуется коммерческое дополнение Grouping Data Grid.
ДЕМО

groupDataGrid — более функциональная версия базовой таблицы данных с широкими возможностями группировки строк. Компонент группирует строки по повторяющимся значениям колонок в сворачиваемые блоки и поддерживает многоуровневую группировку и изменение ее порядка перетаскиванием.

XML-элемент

groupDataGrid

Java-класс

GroupDataGrid

Основы

Объявите пространство имен groupg в XML-дескрипторе экрана:

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

Studio автоматически добавляет пространство имен, когда вы добавляете компонент с помощью действия Add Component на верхней панели действий. См. Палитра компонентов.

В следующем примере клиенты сгруппированы по значениям колонки Grade.

groupdatagrid basic
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 В экране объявлено пространство имен groupg, используемое компонентом.
2 Изначально данные группируются по свойству grade; можно добавить другие уровни группировки.
3 Определение колонки группировки.

Привязка данных

Привязка данных — это связывание визуального компонента с контейнером данных. Чтобы связать компонент с данными, используйте атрибут dataContainer со ссылкой на контейнер коллекции. См. пример выше.

Элемент группы

Элементы группы — это специальные записи, создаваемые при группировке. Они отображаются как строки, содержащие только заголовок группы.

groupdatagrid group items

Для отображения элементов группы уровень привязки данных создаёт временный пустой экземпляр сущности или DTO. Этот экземпляр не добавляется в контейнер коллекции и существует только в памяти на время группировки.

Скрытие счётчика элементов группы

По умолчанию элементы группы отображают количество вложенных записей. Чтобы скрыть это число, используйте свойство displayItemCount элемента groupColumn.

groupdatagrid hide count

Многоуровневая группировка

Компонент поддерживает группировку по нескольким колонкам. Щёлкните значок колонки группировки, чтобы открыть диалог Group by, а затем добавьте или удалите колонки.

groupdatagrid multiple

Сортировка

Настройка сортировки такая же, как в dataGrid. Атрибут sortByGroupEnabled определяет, влияет ли сортировка на порядок групп.

Отключение группировки

Чтобы запретить пользователям группировку по определённой колонке, установите её свойству groupAllowed значение false. Это убирает колонку из диалога Group by. В примере ниже колонка Country не может быть сгруппирована:

groupdatagrid groupallowed
XML code 
<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>

Чтобы полностью отключить группировку для пользователей, установите displayColumnsGrouperOnIconClick="false" на элементе groupColumn.

Группировку по умолчанию можно всё равно задать с помощью элемента groupBy или программно, вызвав метод groupBy().

Настраиваемая колонка группировки

Чтобы использовать нестандартное значение для группировки, опишите новое свойство группировки в контроллере экрана. В следующем примере вводится новое свойство группировки, объединяющее имя и фамилию.

Такое синтетическое свойство не сортируется автоматически. Чтобы включить сортировку, укажите свойства сортировки в дескрипторе свойства группировки с помощью .withSortProperties(…​).

groupdatagrid custom column
XML code 
<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 code 
@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 Предоставляет запасной вариант отображения для колонки Full Name, когда она не участвует в группировке; без этого колонка будет отображаться пустой.

Экспорт в Excel

Функциональность экспорта предоставляется бесплатным дополнением Grid Export Actions, которое поддерживает все виды таблиц: groupDataGrid, dataGrid и treeDataGrid.

groupdatagrid export

Дополнение предоставляет три варианта экспорта. Они влияют как на охват данных, так и на формат итоговой таблицы:

  • Все строки — экспортирует все строки, разворачивая группировку в плоский список.

  • Текущая страница — экспортирует только видимые строки, сохраняя структуру группировки как в таблице.

  • Выбранные строки — экспортирует выбранные строки, разворачивая группировку в плоский список.

Оформление

Темы

ДЕМО

Настройте темы с помощью свойства themeNames. Можно применять несколько тем одновременно. Темы такие же, как в dataGrid.

Иконка группировки

Компонент отображает + для свёрнутой группы и - для развёрнутой. Чтобы изменить иконки, добавьте нужные значки в таблицу стилей приложения. Замените значения content по умолчанию на коды нужных символов (например, e7c1 и e7bf из коллекции иконок шрифта Vaadin):

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

    &[expanded]::part(toggle)::before {
        content: "\e7bf";
    }
}
groupdatagrid groupicon
Подробнее см. стилизуемые части компонентов.

Иконка колонки группировки

Иконка колонки группировки настраивается через атрибут groupIcon элемента groupColumn. Чтобы скрыть иконку, установите groupIconVisible в значение false.

Атрибуты

Общие атрибуты выполняют одну и ту же роль для всех компонентов. Ниже перечислены атрибуты, общие с dataGrid, и атрибуты, уникальные для groupDataGrid:

Имя Описание По умолчанию

aggregatable

Если true, включает агрегацию колонок. См. Агрегация данных.

false

columnReorderingAllowed

Если true, позволяет пользователям изменять порядок колонок.

false

emptyStateText

Текст, отображаемый при отсутствии данных в таблице. Чтобы удалить текущее содержимое пустого состояния, укажите null. См. Отображение при отсутствии данных.

–

selectionMode

Устанавливает режим выделения элементов. Допустимые значения: SINGLE, MULTI.

SINGLE

aggregationPosition

Если данные в компоненте aggregatable, определяет, отображается ли строка агрегации выше или ниже остальных строк. Возможные значения: TOP или BOTTOM. См. Агрегация данных.

BOTTOM

allRowsVisible

Если true, таблица отображает все строки одновременно без полос прокрутки, фактически отключая виртуальную прокрутку. Это означает, что вместо рендеринга только видимых строк и подгрузки дополнительных при прокрутке пользователем таблица отображает все строки в DOM одновременно.

Использование этой функции не рекомендуется при большом количестве элементов, так как это может вызвать проблемы с производительностью.

false

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

Компонент поддерживает следующие общие атрибуты:

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

Обработчики

Общие обработчики настраиваются одинаково для всех компонентов. Ниже перечислены обработчики, общие с dataGrid, и обработчики, уникальные для groupDataGrid:

Чтобы сгенерировать заглушку обработчика в Jmix Studio, используйте вкладку Handlers панели инспектора Jmix UI, или команду Generate Handler, доступную на верхней панели контроллера экрана и через меню Code → Generate (Alt+Insert / Cmd+N).
Имя Описание

CellFocusEvent

com.vaadin.flow.component.grid.CellFocusEvent срабатывает при фокусировке ячейки таблицы. Соответствует DOM-событию grid-cell-focus.

CollapseEvent

Срабатывает при свёртывании группы.

ColumnReorderEvent

com.vaadin.flow.component.grid.ColumnReorderEvent срабатывает при изменении порядка колонок таблицы. Соответствует DOM-событию column-reorder-all-columns.

ColumnResizeEvent

com.vaadin.flow.component.grid.ColumnResizeEvent срабатывает при изменении пользователем ширины колонки. Соответствует DOM-событию column-drag-resize.

ExpandEvent

Срабатывает при развёртывании группы.

GridDragEndEvent

com.vaadin.flow.component.grid.dnd.GridDragEndEvent — событие завершения перетаскивания строк dataGrid. Соответствует DOM-событию grid-dragend.

GridDragStartEvent

com.vaadin.flow.component.grid.dnd.GridDragStartEvent — событие начала перетаскивания строк dataGrid. Соответствует DOM-событию grid-dragstart.

GridDropEvent

com.vaadin.flow.component.grid.dnd.GridDropEvent — событие сброса, происходящее в таблице данных или её строках. Соответствует DOM-событию grid-drop.

GroupItemClickEvent

Срабатывает при щелчке по строке, соответствующей элементу группы.

GroupItemDoubleClickEvent

Срабатывает при двойном щелчке по строке, соответствующей элементу группы.

GroupingChangedEvent

Срабатывает при изменении группировки — добавлении или удалении колонок.

ItemClickEvent

com.vaadin.flow.component.grid.ItemClickEvent срабатывает при щелчке по элементу таблицы. Соответствует DOM-событию item-click.

ItemDoubleClickEvent

com.vaadin.flow.component.grid.ItemDoubleClickEvent срабатывает при двойном щелчке по элементу таблицы. Соответствует DOM-событию item-double-click.

SelectionEvent

Событие выбора, унифицирующее доступ к событию выбора для компонентов с множественным и одиночным выбором (в том числе когда требуется только один выбранный элемент).

SortEvent

com.vaadin.flow.data.event.SortEvent — событие, описывающее изменение сортировки в DataProvider. Отправляется реализациями SortNotifier.

dataGenerator

Добавляет генератор данных для таблицы. Если генератор уже добавлен, ничего не делает. См. интерфейс com.vaadin.flow.data.provider.HasDataGenerators.

dragFilter

Позволяет определить, какие строки можно перетаскивать, вместо включения этой возможности для всех строк с помощью rowsDraggable.

dropFilter

Позволяет определить, какие строки являются допустимыми целями для сброса.

enterPressHandler

Обрабатывает событие нажатия пользователем клавиши Enter.

groupPartNameGenerator

Генерирует части имён CSS-классов для элементов группы на основе заданных условий. Позволяет настраивать внешний вид элементов группы.

groupTooltipGenerator

Создаёт всплывающую подсказку для группы на основе заданных условий.

itemSelectableProvider

Задаёт предикат для проверки, может ли пользователь выбрать или снять выбор с конкретного элемента таблицы. Предикат получает экземпляр элемента и должен возвращать true, если пользователь может изменить состояние выбора этого элемента, и false в противном случае.

partNameGenerator

Генерирует части имён CSS-классов для ячеек на основе заданных условий. Позволяет настраивать внешний вид ячеек в зависимости от отображаемых данных.

sortBuilderDelegate

Создает объект DataGridSort из GroupDataGridSortContext, позволяя сопоставить колонки с пользовательскими компараторами и выражениями сортировки базы данных. См. Делегат построения сортировки.

tooltipGenerator

Создаёт всплывающую подсказку для ячейки колонки на основе заданных условий. См. интерактивный пример.

Компонент поддерживает следующие общие обработчики:

AttachEvent - BlurEvent - DetachEvent - FocusEvent

Элементы

groupDataGrid может содержать непосредственные вложенные элементы actions, groupBy, columns, contextMenu и emptyStateComponent. Элемент columns может содержать column, groupColumn и editorActionsColumn. Общие элементы таблицы описаны в разделах actions, contextMenu и emptyStateComponent.

Чтобы добавить элемент к выбранному компоненту, нажмите кнопку Add в панели инспектора Jmix UI.

groupBy

Элемент groupBy содержит один или несколько элементов columnRef, определяющих, по каким колонкам выполняется группировка.

columnRef

Элемент columnRef определяет колонку, используемую для группировки. Обязательный атрибут key должен совпадать с ключом объявленной колонки.

columns

Элемент columns содержит отдельные элементы column и задаёт набор атрибутов, общих для этих колонок. Он поддерживает includeAll, exclude, sortable, resizable и filterable, как описано для колонок dataGrid.

column

Элемент column описывает отдельную колонку. Атрибуты, заданные для конкретной column, имеют приоритет над атрибутами columns. Элемент поддерживает конфигурацию колонки dataGrid и дополнительный атрибут groupAllowed, который определяет возможность группировки по колонке. См. Отключение группировки.

groupColumn

Элемент groupColumn описывает колонку, используемую для группировки, и ее относительное положение среди других колонок. Он может содержать вложенный элемент groupIcon, задающий пользовательский компонент значка.

Название Описание Значение по умолчанию

autoHidden

Определяет, скрывается ли колонка группировки автоматически, если сгруппированные свойства отсутствуют.

—

autoWidth

Определяет, рассчитывается ли ширина колонки по ее содержимому.

—

displayColumnsGrouperOnIconClick

Определяет, открывает ли щелчок по значку группировки диалог Group by.

—

displayItemsCount

Определяет, отображается ли в заголовке группы количество вложенных элементов. См. Скрытие счетчика элементов группы.

—

flexGrow

Определяет, как колонка расширяется относительно других колонок.

—

footer

Задает текст нижнего колонтитула колонки.

—

frozen

Закрепляет колонку у начального края таблицы.

—

frozenToEnd

Закрепляет колонку у конечного края таблицы.

—

groupIcon

Задает значок группировки по имени значка Vaadin. Вложенный элемент groupIcon имеет приоритет, если требуется компонент значка.

—

groupIconVisible

Определяет видимость значка группировки.

—

header

Задает текст заголовка колонки.

—

key

Задает ключ для идентификации колонки группировки.

—

resizable

Определяет, может ли пользователь изменять ширину колонки.

—

sortable

Определяет, может ли пользователь сортировать данные по колонке группировки.

—

visible

Определяет видимость колонки.

—

width

Задает ширину колонки в единицах CSS.

—