AG grid предназначен для работы с большими таблицами. Компонент поддерживает сортировку, виртуальную прокрутку, изменение ширины и порядка колонок. Основан на библиотеке ag-grid-angular.
Для единства стиля таблиц в проектах создана тема @koobiq/ag-grid-angular-theme. Она включает готовые стили, соответствующие дизайн-системе. Тема поддерживает основные функции AG grid и упрощает настройку внешнего вида таблицы.
Установите следующие пакеты:
npm install @koobiq/ag-grid-angular-theme@^34 ag-grid-community@^34 ag-grid-angular@^34
Импортируйте тему в основной файл стилей styles.scss:
@use '@koobiq/ag-grid-angular-theme';
Примените тему для <ag-grid-angular> в шаблоне:
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';
@Component({
imports: [AgGridModule, KbqAgGridThemeModule],
template: `<ag-grid-angular kbqAgGridTheme />`
})
Полная документация по использованию темы хранится в репозитории на GitHub.
Для этого добавьте атрибут kbqAgGridThemeDisableCellFocusStyles к <ag-grid-angular>:
<ag-grid-angular kbqAgGridTheme kbqAgGridThemeDisableCellFocusStyles />
Директива kbqAgGridRowActions добавляет панель действий, появляющуюся при наведении на строку.
Директива kbqAgGridRowGroup реализует группировку строк на стороне клиента. Подключите её к ag-grid-angular, передайте исходные данные через [kbqAgGridRowGroupRowData] вместо [rowData] и укажите колонки группировки через [(kbqAgGridRowGroupCols)].
Состояние свёрнутых/развёрнутых групп и выделение строк можно сохранять независимо друг от друга: укажите уникальный ключ в kbqAgGridRowGroupCollapsedState и kbqAgGridRowGroupSelectionState, подключив провайдеры хранилища через kbqAgGridRowGroupCollapsedStateStoreProvider и kbqAgGridRowGroupSelectionStateStoreProvider.
Компонент Actions panel позволяет выполнять массовые действия над строками, выделенными в таблице. Чтобы панель не перекрывала последние строки таблицы, при её открытии добавляется padding-bottom для .ag-body-viewport.
Длинный список можно уместить в одну строку ячейки: Overflow items скрывает то, что не помещается по ширине, и пересчитывает скрытое при изменении ширины колонки. Скрытые элементы можно раскрыть прямо в ячейке или показать полным списком в Popover. Чтобы высота строки менялась вместе с содержимым, включите для колонки autoHeight.
Директива kbqAgGridCopyByCtrlC позволяет копировать выделенные строки в буфер обмена при помощи комбинации клавиш Ctrl+C.
Для экспорта отображаемых данных (с учётом активных фильтров, сортировки и форматирования) можно использовать собственный API таблицы. Метод api.exportDataAsCsv() позволяет скачать CSV-файл без дополнительных зависимостей. Другие форматы можно получить на основе значений ячеек таблицы с помощью сторонних библиотек — например, XLSX с помощью xlsx, а PDF — с помощью jspdf и jspdf-autotable.
Директива kbqAgGridStatusBar добавляет настраиваемую панель под таблицей.
Директивы сохраняют и восстанавливают состояние таблицы после перезагрузки страницы.
По умолчанию используется LocalStorageStore. При необходимости можно переключиться на QueryParamsStore.
Директива kbqAgGridColumnState сохраняет сортировку, порядок, видимость и ширину колонок. Добавьте её с уникальным ключом и подключите провайдер хранилища через kbqAgGridColumnStateStoreProvider.
Директива kbqAgGridFilterState сохраняет модели фильтров колонок. Добавьте её с уникальным ключом и подключите провайдер хранилища через kbqAgGridFilterStateStoreProvider.
Директива kbqAgGridQuickFilterState сохраняет значение быстрого фильтра. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridQuickFilterStateStoreProvider и привяжите значение поля ввода через [(kbqAgGridQuickFilterStateValue)].
Директива kbqAgGridExternalFilterState сохраняет значение внешнего фильтра. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridExternalFilterStateStoreProvider, привяжите значение через [(kbqAgGridExternalFilterStateValue)] и передайте функцию проверки строк через kbqAgGridExternalFilterStatePass.
Директива kbqAgGridRowSelectionState сохраняет выделение строк. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridRowSelectionStateStoreProvider и укажите getRowId.
Директива kbqAgGridRowFocusState сохраняет сфокусированную ячейку. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridRowFocusStateStoreProvider и укажите getRowId.
Директива kbqAgGridColumnMenu добавляет в правый верхний угол таблицы кнопку, которая открывает меню управления колонками. В меню можно показывать и скрывать колонки, менять их порядок перетаскиванием, закреплять слева или справа и находить колонку по названию. Кнопка сброса возвращает колонки к исходному состоянию.
Ограничения задаются через ColDef:
lockVisible: true запрещает скрывать колонку. Последнюю видимую колонку скрыть нельзя в любом случае.lockPinned: true запрещает закреплять и откреплять колонку.По умолчанию используются русские подписи. Для смены языка подключите провайдер:
providers: [kbqAgGridColumnMenuLabelsProvider(KBQ_AG_GRID_COLUMN_MENU_LABELS_EN)];
Директива kbqAgGridLoadingOverlay управляет состоянием загрузки таблицы: когда значение true, поверх строк отображается скелетон-оверлей. Число строк и колонок скелетона задаётся через kbqAgGridLoadingOverlayConfigProvider.
KbqAgGridSkeletonCellRenderer используется совместно с моделью бесконечной прокрутки (rowModelType="infinite"). Пока блок данных не загружен (params.data === undefined), ячейки отображают скелетон-заглушки.
При бесконечной прокрутке данные подгружаются блоками, поэтому выбрать их все обычным списком нельзя — большая часть еще не загружена. Директива kbqAgGridInfiniteSelection инвертирует выбор: вместо перечня выбранных строк она хранит признак «выбраны все» и список исключений.
Такое состояние повторяет условие «все, кроме указанных ID», поэтому его можно передать на сервер, не загружая все строки.
Директиве нужны два параметра:
kbqAgGridInfiniteSelectionDatasource принимает источник данных. Когда выбраны все строки, подгружаемые блоки добавляются в выбор автоматически.getRowId возвращает стабильный уникальный идентификатор строки.Вы можете добавить пользовательские сочетания клавиш, добавив соответствующие директивы к вашему компоненту <ag-grid-angular>.
Клавиша |
Действие | Директива |
|---|---|---|
| Tab | Перейти к следующей строке | kbqAgGridToNextRowByTab |
| Shift + ↓↑ | Выделить несколько строк | kbqAgGridSelectRowsByShiftArrow |
| Ctrl + click | Выделить строку | kbqAgGridSelectRowsByCtrlClick |
| Ctrl + C | Копировать выделенные строки | kbqAgGridCopyByCtrlC |
| Shift + click | Выделить диапазон строк | kbqAgGridSelectRowsByShiftClick |
| Ctrl + A | Выделить все строки | kbqAgGridInfiniteSelection |
Больше информации о сочетаниях клавиш можно найти в документации ag-grid-angular.