API корня
DataGrid — корневой контейнер активной ячейки и навигации с клавиатуры.
| Проп | Тип | По умолчанию |
|---|---|---|
ref | Ref<HTMLDivElement> | — |
| Ref на корневой элемент сетки. | ||
apiRef | Ref<DataGridApiRef<K>> | — |
Ref на императивный API сетки. Предоставляет низкоуровневые структуры для сложных сценариев: grid — помощник навигации по матрице; keyMap — Map<K, [row, col]> для быстрого поиска | ||
wrap | DataGridWrap | — |
| Режим зацикливания навигации. 'horizontal' — переход по столбцам в пределах строки; 'vertical' — переход по строкам в пределах столбца; 'both' — оба поведения; undefined — без зацикливания | ||
defaultActive | K | '' |
| Неконтролируемый начальный ключ активной (сфокусированной) ячейки. | ||
active | K | — |
| Контролируемый ключ активной (сфокусированной) ячейки. | ||
onChangeActive | (active: K) => void | — |
| Вызывается при изменении ключа активной (сфокусированной) ячейки. | ||
exclude | DataGridExclude<K> | — |
Исключает ячейки из обхода фокусом. Может быть: одним ключом; массивом ключей; предикатом (key) => boolean | ||
rowDelta | number | — |
Шаг навигации по строкам для PageUp/PageDown. undefined — переход к первой/последней строке; number — сдвиг на N строк относительно текущей | ||
onArrow | (e: KeyboardEvent<HTMLDivElement>, node: MatrixNode<HTMLElement, K>, prevNode: MatrixNode<HTMLElement, K>) => void | — |
| Вызывается на каждом шаге навигации стрелками после смены фокуса | ||
Также принимает все атрибуты <div>.
API дочерних частей
DataGridRowGroup
Группирует строки для регистрации в навигации.
| Проп | Тип | По умолчанию |
|---|---|---|
scope | DataGridScope | — |
| Необязательная логическая группа для ячеек сетки. Позволяет DataGrid считать ячейки частью одной страницы или раздела. | ||
Также принимает все атрибуты <div>.
DataGridRow
Единица регистрации строки.
| Проп | Тип | По умолчанию |
|---|---|---|
rowобязательный | number | — |
| Индекс строки (с нуля) для всех дочерних ячеек. Передаётся потомкам через контекст. | ||
Также принимает все атрибуты <div>.
DataGridCell
Единица регистрации ячейки.
| Проп | Тип | По умолчанию |
|---|---|---|
colобязательный | number | — |
Индекс столбца ячейки (с 0). Вместе с индексом строки из контекста строки образует координаты сетки: [row, col]. | ||
ref | Ref<HTMLDivElement> | — |
Внешний ref на корневой элемент ячейки. Объединяется с внутренней регистрацией itemRef([row, col], key), если ячейка не исключена. | ||
cellKey | DataGridCellKey | — |
Стабильный ключ, идентифицирующий ячейку в матрице DataGrid. Если не задан, ключ выводится из row/col как ${row}:${col}. | ||
asChild | boolean | false |
Если true, рендерит дочерние элементы через Slot и передаёт пропсы и ref дочернему элементу вместо использования нативного <div>. | ||
excluded | boolean | — |
| Исключает ячейки из обхода фокусом. Переопределяет значение из корневого DataGrid | ||
Также принимает все атрибуты <div>.
Хуки
useDataGridContext
Продвинутый хук для координации на уровне корня сетки.
useDataGridRowContext
Продвинутый хук для кастомных абстракций на уровне строки.
Типы
| Тип | Определение | Примечания |
|---|---|---|
DataGridCellKey | контракт ключа ячейки | Обычно строится из строки и столбца. |
DataGridCoordinates | форма координат строка/столбец | Используется логикой навигации. |
DataGridWrap | объединение режимов переноса | По горизонтали, по вертикали или в обе стороны. |
DataGridExclude | контракт исключений | Управление навигацией в разреженной сетке. |
DataGridApiRef | контракт API ref | Продвинутые интеграции. |
DataGridScope | идентификатор области | При необходимости разделяет логические группы сеток. |
Модель состояния
- Активная ячейка может быть контролируемой или неконтролируемой.
- Навигация зависит от порядка регистрации строк и ячеек.
- Исключения и режим переноса напрямую влияют на модель клавиатуры.
- Корень — фундаментальный слой; семантику выбора и пикера добавляют производные компоненты.
Замечания по интеграции
- Для статичного отображения данных предпочитайте
Table. - Используйте правила исключений, когда видимая матрица разрежена.
- Используйте
rowDelta, когда PageUp/PageDown должны сдвигать на фиксированное число строк, а не прыгать к краям. - Тщательно перепроверяйте интерактивное содержимое внутри ячеек.