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.
Директива kbqAgGridRowDetail раскрывает строку и показывает под ней произвольный компонент. Передайте компонент через kbqAgGridRowDetailComponent и укажите getRowId. Данные строки и метод collapse() компонент получает через токен KBQ_AG_GRID_ROW_DETAIL_PARAMS.
Поведение раскрытых строк настраивается параметрами:
| Параметр | Описание |
|---|---|
kbqAgGridRowDetailSingleExpand | Оставляет раскрытой только одну строку |
kbqAgGridRowDetailFilled | Заливает раскрытую строку фоном |
kbqAgGridRowDetailSticky | Удерживает раскрытую часть на месте при горизонтальной прокрутке |
Методы директивы доступны через #rowDetail="kbqAgGridRowDetail":
| Метод | Описание |
|---|---|
expand(id) | Раскрывает строку |
collapse(id) | Сворачивает строку |
toggle(id) | Раскрывает или сворачивает строку |
collapseAll() | Сворачивает все строки |
В примере toggle() вызывают клик по ячейке и Enter на строке. Раскрытая часть не является ячейкой, поэтому клик по ней строку не сворачивает, а клик по чекбоксу выделения её не раскрывает.
Подписи кнопки раскрытия для скринридеров по умолчанию на русском языке. Для смены языка подключите провайдер:
providers: [kbqAgGridRowDetailLabelsProvider(KBQ_AG_GRID_ROW_DETAIL_LABELS_EN)];Компонент Actions panel позволяет выполнять массовые действия над строками, выделенными в таблице. Чтобы панель не перекрывала последние строки таблицы, при её открытии добавляется padding-bottom для .ag-body-viewport.
Компонент Content panel показывает быстрый просмотр строки, выделенной в таблице, сдвигая таблицу, а не перекрывая её.
Длинный список можно уместить в одну строку ячейки: Overflow items скрывает то, что не помещается по ширине, и пересчитывает скрытое при изменении ширины колонки. Скрытые элементы можно раскрыть прямо в ячейке или показать полным списком в Popover. Чтобы высота строки менялась вместе с содержимым, включите для колонки autoHeight.
Директива kbqAgGridCopyByCtrlC позволяет копировать выделенные строки в буфер обмена при помощи комбинации клавиш Ctrl+C.
Для экспорта отображаемых данных (с учётом активных фильтров, сортировки и форматирования) можно использовать собственный API таблицы. Метод api.exportDataAsCsv() позволяет скачать CSV-файл без дополнительных зависимостей. Другие форматы можно получить на основе значений ячеек таблицы с помощью сторонних библиотек — например, XLSX с помощью write-excel-file, а PDF — с помощью jspdf и jspdf-autotable.
Директива kbqAgGridStatusBar добавляет настраиваемую панель под таблицей.
Директивы сохраняют и восстанавливают состояние таблицы после перезагрузки страницы.
По умолчанию используется LocalStorageStore. При необходимости можно переключиться на QueryParamsStore.
Директива kbqAgGridColumnState сохраняет сортировку, порядок, видимость и ширину колонок. Добавьте её с уникальным ключом и подключите провайдер хранилища через kbqAgGridColumnStateStoreProvider.
Директива kbqAgGridFilterState сохраняет модели фильтров колонок. Добавьте её с уникальным ключом и подключите провайдер хранилища через kbqAgGridFilterStateStoreProvider.
Директива kbqAgGridQuickFilterState сохраняет значение быстрого фильтра. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridQuickFilterStateStoreProvider и привяжите значение поля ввода через [(kbqAgGridQuickFilterStateValue)].
Директива kbqAgGridExternalFilterState сохраняет значение внешнего фильтра. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridExternalFilterStateStoreProvider, привяжите значение через [(kbqAgGridExternalFilterStateValue)] и передайте функцию проверки строк через kbqAgGridExternalFilterStatePass.
Директива kbqAgGridRowSelectionState сохраняет выделение строк. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridRowSelectionStateStoreProvider и укажите getRowId.
Директива kbqAgGridRowFocusState сохраняет сфокусированную ячейку. Добавьте её с уникальным ключом, подключите провайдер хранилища через kbqAgGridRowFocusStateStoreProvider и укажите getRowId.
Директива kbqAgGridSettingsMenu добавляет в правый верхний угол таблицы кнопку меню параметров. По умолчанию в меню два пункта:
| Пункт | Описание |
|---|---|
kbqAgGridSettingsMenuColumnsItem() | Показ, скрытие, порядок и закрепление колонок, поиск по названию |
kbqAgGridSettingsMenuSortItem() | Сортировка по нескольким колонкам |
Кнопка сброса возвращает колонки и сортировку к исходному состоянию.
Ограничения задаются через ColDef:
lockVisible: true запрещает скрывать колонку. Последнюю видимую колонку скрыть нельзя в любом случае.lockPinned: true запрещает закреплять и откреплять колонку.По умолчанию используются русские подписи. Для смены языка подключите провайдеры:
providers: [
kbqAgGridSettingsMenuLabelsProvider(KBQ_AG_GRID_SETTINGS_MENU_LABELS_EN),
kbqAgGridColumnMenuLabelsProvider(KBQ_AG_GRID_COLUMN_MENU_LABELS_EN)
];Директива kbqAgGridLoadingOverlay управляет состоянием загрузки таблицы: когда значение true, поверх строк отображается скелетон-оверлей.
Заглушка-скелет занимает место таблицы до загрузки. Независимо от содержимого будущей таблицы заглушка состоит из шапки, 3 столбцов и 3 строк. Число столбцов и строк можно регулировать через kbqAgGridLoadingOverlayConfigProvider. Первый столбец имеет фиксированный размер, остальные растягиваются поровну. Полоски-заглушки в ячейках имитируют реальное содержимое и занимают разную ширину.
После инициализации таблицы начинается загрузка данных. Для единства при загрузке остается заглушка из трех строк, но теперь она отражает реальный состав колонок и их ширину, а также колонку с чекбоксами. Полоски-заглушки в ячейках по-прежнему имеют разную ширину, чтобы имитировать реальное содержимое.
KbqAgGridSkeletonCellRenderer показывает скелетон в ячейках строк, которые модель бесконечной прокрутки (rowModelType="infinite") ещё не загрузила. Для колонки выделения есть свой скелетон: пока данных нет, чекбокс недоступен.
При начальной загрузке таблица сразу запрашивает первую и вторую порции данных, а при прокрутке остается на шаг впереди пользователя.
Если порцию не удалось загрузить, директива kbqAgGridLoadError показывает на последней строке сообщение об ошибке со ссылкой для повтора:
Чтобы посмотреть эти варианты в примере, переключите параметры под таблицей.
Если в таблице нет скелетонов, пока данные грузятся, вместо них можно показывать текстовый индикатор загрузки. Он занимает всю ширину строки, поэтому его подпись не сдвигается колонкой выделения.
При бесконечной прокрутке данные подгружаются блоками, поэтому выбрать их все обычным списком нельзя — большая часть еще не загружена. Директива 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.