API корня
| Проп | Тип | По умолчанию |
|---|---|---|
selection | S | 'single' |
Режим выбора. 'single' — одновременно можно выбрать только одну ячейку; 'multiple' — независимый множественный выбор (переключение по ячейке); 'range' — выбор диапазона между двумя точками (Shift + стрелки или перетаскивание указателем) | ||
disabled | DataGridDisabled<K> | — |
Предикат или набор отключённых ячеек. Может быть: функцией (key) => boolean; массивом отключённых ключей; одним ключом. Отключённые ячейки нельзя выбрать или сфокусировать. | ||
excludeDisabled | boolean | true |
| — | ||
expandable | boolean | true |
| Включает расширение диапазонов выбора (Shift + стрелка или перетаскивание мышью). | ||
defaultActive | K | — |
| Неконтролируемая начальная активная ячейка. | ||
active | K | — |
| Контролируемая активная ячейка. | ||
selected | S extends "single" ? K | null : K[] | — |
Контролируемые выбранные ячейки. В режиме 'single' значение null означает контролируемое состояние без выбора. | ||
defaultSelected | S extends "single" ? K : K[] | — |
| Неконтролируемые изначально выбранные ячейки. | ||
from | K | — |
Границы диапазона. Если заданы, ограничивают выбор ячейками между from и to на основе функции compare. | ||
to | K | — |
| — | ||
resolveRange | (start: DataGridResolveValue<K>, end: DataGridResolveValue<K>, grid: Grid<HTMLElement, K>) => K[] | — |
Собственная логика построения диапазона для selection="range". По начальному и конечному значениям возвращает список ключей, образующих диапазон. | ||
equals | (start: K | undefined, end: K | undefined) => boolean | — |
Собственная функция сравнения двух ключей ячеек на равенство. По умолчанию — строгое равенство (===). | ||
compare | (a: K, b: K) => -1 | 0 | 1 | — |
Собственная функция упорядочивания двух ключей ячеек. Должна возвращать -1, 0 или 1. | ||
onSelectCell | (value: S extends 'single' ? K : K[]) => void | — |
| Вызывается, когда пользователь выбирает ячейку. Получает список ключей выбранных ячеек. | ||
onChangeActive | (active: K) => void | — |
| Вызывается при изменении активной (сфокусированной) ячейки. | ||
ref | Ref<HTMLDivElement> | — |
| Ref на корневой элемент сетки. | ||
apiRef | Ref<DataGridApiRef<K>> | — |
Ref на императивный API сетки. Предоставляет низкоуровневые структуры для сложных сценариев: grid — помощник навигации по матрице; keyMap — Map<K, [row, col]> для быстрого поиска | ||
wrap | DataGridWrap | — |
| Режим зацикливания навигации. 'horizontal' — переход по столбцам в пределах строки; 'vertical' — переход по строкам в пределах столбца; 'both' — оба поведения; undefined — без зацикливания | ||
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 дочерних частей
DataGridSelectableRowGroup
Группирует строки и может разделять области в продвинутых композициях.
| Проп | Тип | По умолчанию |
|---|---|---|
scope | DataGridScope | — |
| Необязательная логическая группа для ячеек сетки. Позволяет DataGrid считать ячейки частью одной страницы или раздела. | ||
Также принимает все атрибуты <div>.
DataGridSelectableRow
Одна строка ячеек матрицы.
| Проп | Тип | По умолчанию |
|---|---|---|
rowобязательный | number | — |
| Индекс строки (с нуля) для всех дочерних ячеек. Передаётся потомкам через контекст. | ||
Также принимает все атрибуты <div>.
DataGridSelectableCell
Одна выбираемая ячейка.
| Проп | Тип | По умолчанию |
|---|---|---|
disabled | boolean | — |
| Отключает выбор кликом и с клавиатуры. Переопределяет значение из корневого DataGrid | ||
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>.
- модель ключей ячеек должна оставаться стабильной между рендерами
Хуки
useDataGridSelectableContext
Продвинутый хук для чтения состояния выбора и отключённости в собственных обёртках ячеек.
Типы
| Тип | Определение | Примечания |
|---|---|---|
DataGridSelectableProps<K, S> | тип пропсов корня | Расширяет DataGridProps<K>. |
DataGridSelectableRowGroupProps | пропсы группы строк | Группировка и поведение областей. |
DataGridSelectableRowProps | пропсы строки | Метаданные координаты строки. |
DataGridSelectableCellProps | пропсы ячейки | Координата ячейки и пропсы рендера. |
DataGridSelection | 'single' | 'multiple' | 'range' | Режим выбора. |
DataGridDisabled<K> | тип карты отключённых ячеек | Предикат, список или ключ. |
Модель состояния
- Активное и выбранное состояния могут быть как контролируемыми, так и неконтролируемыми.
- Режим диапазона использует логику расширения, управляемую клавиатурой и движением указателя.
- Отключённые и исключённые ячейки меняют и выбор, и навигацию.
Заметки по интеграции
- Сохраняйте стабильный порядок ключей при использовании
compareи логики диапазонов. - Используйте
DataGridPicker, когда визуальный слой пикера должен быть стандартным. - Проверяйте перетаскивание указателем, расширение с
Shiftи циклическую навигацию вместе в реальных сценариях.