useTableCell для ячеек

Хук useTableCell предназначен для управления поведением и доступностью отдельных ячеек таблицы в компонентах React, построенных с использованием библиотеки React Aria. Он обеспечивает правильное взаимодействие с клавиатурой, фокусом и технологией чтения с экрана, соответствуя стандартам ARIA для таблиц.

Импорт и базовое использование

import { useTableCell } from '@react-aria/table';
import { useTableState } from '@react-stately/table';
import { Table } from '@react-stately/table';

Для корректной работы useTableCell требуется состояние таблицы (tableState) и объект информации о конкретной ячейке (node).

const cellProps = useTableCell({ node, column }, state);
  • node – объект типа TableNode, содержащий данные и метаданные ячейки.
  • column – объект колонки, если требуется доступ к специфическим параметрам колонки.
  • state – состояние таблицы, создаваемое через useTableState.

Хук возвращает объект с свойствами, которые необходимо развернуть на элемент ячейки:

<td {...cellProps}>
  {node.rendered}
</td>

Доступные свойства из useTableCell

Хук возвращает следующие ключевые свойства:

  • role – устанавливает ARIA-роль ячейки (cell или gridcell).
  • tabIndex – управляет фокусом, чтобы только активная ячейка была доступна для клавиатуры.
  • aria-selected – используется для выделения ячейки в интерактивных таблицах.
  • aria-colindex – индекс колонки для технологий чтения с экрана.
  • aria-rowindex – индекс строки для технологий чтения с экрана.
  • onFocus – обработчик фокуса для поддержки клавиатурной навигации.
  • onKeyDown – обработчик нажатий клавиш, обеспечивающий навигацию по таблице с помощью стрелок.

Пример использования в компоненте

function TableCell({ node, column, state }) {
  const { cellProps } = useTableCell({ node, column }, state);

  return (
    <td {...cellProps}>
      {node.rendered}
    </td>
  );
}

function ExampleTable() {
  const state = useTableState({
    columns: ['Name', 'Age', 'Location'],
    items: [
      { id: 1, Name: 'Alice', Age: 25, Location: 'NY' },
      { id: 2, Name: 'Bob', Age: 30, Location: 'LA' }
    ]
  });

  return (
    <table>
      <thead>
        <tr>
          {state.collection.columns.map(column => (
            <th key={column.key}>{column.rendered}</th>
          ))}
        </tr>
      </thead>
      <tbody>
        {state.collection.rows.map(row => (
          <tr key={row.key}>
            {row.childNodes.map(cell => (
              <TableCell key={cell.key} node={cell} column={cell.column} state={state} />
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

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

Управление фокусом и выделением

useTableCell интегрируется с состоянием таблицы и позволяет:

  • Перемещать фокус по ячейкам с помощью стрелок вверх/вниз/влево/вправо.
  • Поддерживать выделение ячейки при использовании aria-selected.
  • Работать с ячейками в интерактивных таблицах, где ячейка может быть элементом управления (например, кнопкой или ссылкой).
const { cellProps } = useTableCell({ node, column }, state);

return (
  <td
    {...cellProps}
    style={{
      outline: cellProps.tabIndex === 0 ? '2px solid blue' : 'none'
    }}
  >
    {node.rendered}
  </td>
);

Такой подход гарантирует, что клавиатурная навигация всегда видима и логична.

Совместимость с другими хуками React Aria

useTableCell часто используется совместно с:

  • useTableRow – для управления поведением строки и правильной структуры ARIA.
  • useTable – для общей конфигурации таблицы и управления состоянием.
  • useTableHeader – если ячейка находится в шапке таблицы.

Это обеспечивает полную согласованность ARIA-ролей и индексов, что критично для экранных ридеров.

Практические рекомендации

  • Всегда передавать объект node и state в useTableCell.
  • Для интерактивных таблиц использовать aria-selected и стилизовать выделенные ячейки.
  • Фокус должен быть на одной ячейке одновременно; для этого tabIndex выставляется динамически.
  • При вложенных компонентах внутри ячейки важно прокидывать cellProps на корневой элемент, чтобы сохранить доступность.

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

Оглавление