Перейти к содержимому
v2.5.0
English
Русский
Документация

DataGrid

DataGrid — составной компонент для навигации по строкам и ячейкам сетки с клавиатуры.
StorybookИсходники

Паттерны

Навигация в духе электронной таблицы

Когда использовать:

пользователи перемещаются по плотной матрице с клавиатуры.

Заметки по композиции:

Задавайте координаты строк и ячеек явно и выбирайте поведение переноса осознанно.

Компромиссы:

Мощное управление с клавиатуры, но интеграция сложнее, чем у статичной таблицы.

team-schedule.tsx · 41 строка
import {
  DataGrid,
  DataGridCell,
  DataGridRow,
  DataGridRowGroup,
} from '@vega-ui/react';
import './examples.css';

const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'];

const rota = [
  { name: 'Maya Chen', shifts: ['Day', 'Day', 'Off', 'Night', 'Night'] },

Разреженная сетка планировщика

Когда использовать:

в визуальной раскладке есть намеренные пробелы.

Заметки по композиции:

Отрисовывайте только существующие ячейки: отсутствующие столбцы вертикальное движение пропускает само. exclude оставьте для ячеек, которые видны, но не должны получать фокус.

Компромиссы:

Навигация следует реальным данным без лишнего учёта, но во всех строках одинаковый индекс столбца должен означать одно и то же.

days-of-the-year.tsx · 55 строк
import { useState } from 'react';
import {
  DataGrid,
  DataGridCell,
  DataGridRow,
  DataGridRowGroup,
  Text,
} from '@vega-ui/react';
import './examples.css';

const year = 2026;
const months = Array.from({ length: 12 }, (_, month) => month);

Контролируемая активная ячейка

Когда использовать:

родительскому сценарию нужно синхронизировать позицию в сетке с другими частями интерфейса.

Заметки по композиции:

Храните состояние active в родителе. Изменение active переносит только позицию табуляции; когда внешний контрол должен перенести и фокус, сфокусируйте ячейку через apiRef.

Компромиссы:

Больше контроля, но и больше работы по согласованию состояния.

controlled-active-cell.tsx · 63 строки
import { useRef, useState } from 'react';
import {
  Button,
  DataGrid,
  DataGridCell,
  DataGridRow,
  DataGridRowGroup,
  Text,
  type DataGridApiRef,
} from '@vega-ui/react';
import './examples.css';

Сравнение

Быстрое правило выбора

Выбирайте DataGrid, когда навигация с клавиатуры между отдельными ячейками — часть основного взаимодействия.

DataGrid или Table

Используйте DataGrid, когда:

  • ячейкам нужно управление активным фокусом
  • важно взаимодействие в духе электронной таблицы

Используйте Table, когда:

  • содержимое в основном статичное
  • семантическое чтение таблицы важнее навигации по ячейкам

DataGrid или DataGridSelectable

Используйте DataGrid, когда:

  • достаточно базовой навигации
  • выбор должен оставаться вне слоя сетки

Используйте DataGridSelectable, когда:

  • выбор строк или ячеек — часть UX

DataGrid или DataGridPicker

Используйте DataGrid, когда:

  • главная задача — навигация по сетке

Используйте DataGridPicker, когда:

  • сетка служит поверхностью выбора значения, а не общей системой навигации по ячейкам

Выбирайте этот компонент, когда

  • перемещение с клавиатуры между ячейками задумано намеренно
  • сетка — скорее модель взаимодействия, чем статичная таблица
  • производные слои выбора или пикера были бы преждевременны

Не выбирайте этот компонент, когда

  • достаточно семантической Table
  • пользователю не нужна навигация по активной ячейке
  • сценарии выбора лучше реализуют производные семейства сетки

Решение проблем

Навигация с клавиатуры работает странно

Симптом

Активная ячейка перемещается не так, как выглядит видимая сетка.

Вероятная причина

Режим переноса или правила исключений не совпадают с отрендеренной раскладкой.

Как проверить

  • посмотрите wrap
  • посмотрите exclude
  • сравните видимую матрицу с путём навигации с клавиатуры

Решение

  • согласуйте правила исключений с реальными пустыми ячейками
  • выберите подходящий для продуктового сценария режим wrap

Активная ячейка не синхронизируется с родителем

Симптом

Интерфейс вроде бы меняет активную ячейку, но состояние родителя отстаёт или расходится.

Вероятная причина

Контролируемое активное состояние не опирается на единый источник истины.

Как проверить

  • посмотрите active
  • посмотрите onChangeActive

Решение

  • храните active в одном источнике состояния у родителя
  • передавайте этот же источник в DataGrid

Интерактивное содержимое ячеек ломает работу с клавиатуры

Симптом

Кнопки или кастомные виджеты внутри ячейки мешают навигации по сетке.

Вероятная причина

Содержимое ячейки конкурирует с собственной моделью фокуса сетки.

Как проверить

  • перейдите в сетку по Tab
  • перемещайтесь с клавиатуры
  • проверьте взаимодействие с содержимым ячейки

Решение

  • сначала упростите содержимое ячейки
  • возвращайте интерактивные контролы, только если модель клавиатуры по-прежнему работает