Data Table

Data Table - это полнофункциональный компонент таблицы, построенный на базе TanStack Table и интегрированный с React Query для асинхронной загрузки данных. Компонент предоставляет богатый набор возможностей для работы с табличными данными, включая drag-and-drop сортировку столбцов, фильтрацию, пагинацию, выбор строк и экспорт данных.

Базовый пример использования примитивов таблицы

Делиться ссылками с активными фильтрами
Использовать кнопки "Назад/Вперед" браузера
Сохранять состояние при перезагрузке страницы

Свойства

DataTablePrimitives Props

Атрибут	Тип	Описание	По умолчанию
size	`"sm" \| "md" \| "lg"`	Размер таблицы	`"md"`
striped	`boolean`	Чередующиеся цвета строк	`false`
bordered	`boolean`	Отображать границы	`true`
hoverable	`boolean`	Эффект при наведении	`true`
isScrollable	`boolean`	Горизонтальная прокрутка	`false`
isExpandable	`boolean`	Поддержка раскрываемых строк	`false`
className	`string`	Дополнительные CSS классы	-

DataTableRoot Props

Атрибут	Тип	Описание	По умолчанию
columns	`ColumnDef<TData>[]`	Определение столбцов TanStack Table (обязательное)	-
queryOptions	`UseQueryOptions \| ((params) => UseQueryOptions)`	Опции для React Query (обязательное)	-
initialPagination	`{ pageIndex: number; pageSize: number; pageSizes?: number[] }`	Начальные настройки пагинации	`{ pageIndex: 1, pageSize: 10 }`
showPageJump	`boolean`	Показать поле быстрого перехода	`true`
showTotalCount	`boolean`	Показать общее количество записей	`false`
showPageSizeSelector	`boolean`	Показать селектор размера страницы	`true`
defaultTotalCountKey	`string`	Ключ для общего количества в ответе API	`"hydra:totalItems"`

Порядок столбцов

Атрибут	Тип	Описание
isCanDrag	`boolean`	Включить drag-and-drop для столбцов
columnOrderStorageKey	`string`	Ключ для хранения порядка
columnOrderStorageType	`"local" \| "api"`	Тип хранилища
externalColumnOrder	`string[]`	Внешний порядок столбцов (для API)
onColumnOrderApiLoad	`() => Promise<string[] \| null>`	Загрузка порядка из API
onColumnOrderApiSave	`(order: string[]) => Promise<void>`	Сохранение порядка в API
onColumnOrderStorageError	`(error: Error) => void`	Обработка ошибок хранилища

Видимость столбцов

Атрибут	Тип	Описание
withEditing	`boolean`	Включить управление видимостью
columnVisibilityStorageKey	`string`	Ключ для хранения видимости
columnVisibilityStorageType	`"local" \| "api"`	Тип хранилища
externalColumnVisibility	`VisibilityState`	Внешнее состояние видимости (для API)
onColumnVisibilityApiLoad	`() => Promise<VisibilityState \| null>`	Загрузка видимости из API
onColumnVisibilityApiSave	`(visibility: VisibilityState) => Promise<void>`	Сохранение видимости в API
onColumnVisibilityStorageError	`(error: Error) => void`	Обработка ошибок хранилища

Фильтрация

Атрибут	Тип	Описание
filters	`DataTableFilter[]`	Определение доступных фильтров
texts	`{ filterButtonLabel?: string; filterApplyButtonLabel?: string; filterCancelButtonLabel?: string }`	Тексты для UI фильтров

Выбор строк

Атрибут	Тип	Описание
selectedActions	`SelectedAction[]`	Действия для выбранных строк
rowIdKey	`keyof TData`	Ключ для ID строки
customRender	`(selectedRows: string[]) => ReactNode`	Кастомный рендер панели выбранных строк

Экспорт

Атрибут	Тип	Описание
withExport	`boolean`	Включить экспорт данных
exportFilename	`string`	Имя файла для экспорта
texts	`{ exportButton?: string; exportCsv?: string; exportExcel?: string }`	Тексты для UI экспорта
onCustomExportCsv	`(data: TData[]) => void`	Кастомная логика экспорта CSV
onCustomExportExcel	`(data: TData[]) => void`	Кастомная логика экспорта Excel

Раскрываемые строки

Атрибут	Тип	Описание
getRowCanExpand	`(row: Row<TData>) => boolean`	Функция определения возможности раскрытия
renderSubComponent	`(props: { row: Row<TData> }) => ReactElement`	Рендер содержимого раскрытой строки

Прочее

Атрибут	Тип	Описание
startContent	`ReactNode`	Контент в начале таблицы
endContent	`ReactNode`	Контент в конце таблицы
drawerProps	`DrawerProps`	Свойства для Drawer (при использовании withEditing)
paginationProps	`Omit<PaginationProps, 'total' \| 'page' \| 'onChange'>`	Дополнительные свойства для пагинации

Используйте aria-label для описания таблицы
Все интерактивные элементы доступны с клавиатуры
Поддержка screen readers через семантические HTML элементы
Фокус управляется корректно при навигации

Best Practices

Всегда указывайте id для столбцов при использовании drag-and-drop или управления видимостью
Используйте useMemo для columns чтобы избежать лишних ререндеров
Оборачивайте в QueryClientProvider и NuqsAdapter для корректной работы
Используйте типы TypeScript для type-safety при работе с данными
Настройте обработку ошибок для API storage с fallback на localStorage