useKeyboard для клавиатурных событий

useKeyboard — это хук, предоставляемый библиотекой React Aria, который позволяет управлять событиями клавиатуры в компонентах React с учётом доступности. Он обеспечивает унифицированный способ обработки нажатий клавиш, учитывая спецификации WAI-ARIA и особенности разных платформ.

Хук возвращает объект, содержащий обработчики событий onKeyDown, onKeyUp и onKeyPress, которые можно напрямую привязать к нужному элементу через пропсы.

import { useKeyboard } from '@react-aria/interactions';

function MyComponent() {
  const { keyboardProps } = useKeyboard({
    onKeyDown: (e) => console.log(`Key down: ${e.key}`),
    onKeyUp: (e) => console.log(`Key up: ${e.key}`)
  });

  return <div {...keyboardProps}>Нажимайте клавиши</div>;
}

Параметры `useKeyboard`

Хук принимает объект с опциями:

onKeyDown – функция, вызываемая при нажатии клавиши. Получает объект события клавиатуры с полями key, code, ctrlKey, shiftKey, altKey и metaKey.
onKeyUp – функция, вызываемая при отпускании клавиши.
onKeyPress – функция, вызываемая при вводе символа (устаревшее, чаще используется onKeyDown).
isDisabled – логическое значение, отключающее обработку клавиш.

Использование isDisabled позволяет динамически управлять интерактивностью компонента:

const { keyboardProps } = useKeyboard({
  onKeyDown: (e) => console.log(e.key),
  isDisabled: true
});

В этом примере обработчики не будут срабатывать до изменения isDisabled на false.

Работа с модификаторами

useKeyboard корректно обрабатывает сочетания клавиш с Shift, Ctrl, Alt и Meta. Это особенно важно для компонентов, где используются горячие клавиши:

const { keyboardProps } = useKeyboard({
  onKeyDown: (e) => {
    if (e.ctrlKey && e.key === 's') {
      e.preventDefault();
      console.log('Сохранение документа');
    }
  }
});

Пример выше демонстрирует обработку Ctrl + S и предотвращение стандартного действия браузера.

Поддержка доступности

React Aria ориентирован на соблюдение стандартов доступности WAI-ARIA. useKeyboard автоматически учитывает:

Управление фокусом через клавиши Tab и Shift + Tab.
Поддержку клавиш навигации (ArrowUp, ArrowDown, ArrowLeft, ArrowRight) для списков, меню и табов.
Игнорирование событий для отключённых элементов или при скрытии контента.

Это позволяет создавать компоненты, совместимые с экранными читалками и другими вспомогательными технологиями.

Примеры практического применения

1. Навигация по списку с клавиатуры

import { useKeyboard } from '@react-aria/interactions';
import { useState } from 'react';

function ListNavigator({ items }) {
  const [focusedIndex, setFocusedIndex] = useState(0);

  const { keyboardProps } = useKeyboard({
    onKeyDown: (e) => {
      if (e.key === 'ArrowDown') {
        setFocusedIndex((prev) => (prev + 1) % items.length);
      } else if (e.key === 'ArrowUp') {
        setFocusedIndex((prev) => (prev - 1 + items.length) % items.length);
      }
    }
  });

  return (
    <ul {...keyboardProps}>
      {items.map((item, index) => (
        <li key={index} style={{ background: index === focusedIndex ? '#ddd' : 'transparent' }}>
          {item}
        </li>
      ))}
    </ul>
  );
}

В этом примере стрелки клавиатуры управляют выделением элементов списка, что соответствует поведению стандартных ARIA-компонентов.

2. Обработка горячих клавиш для действий

const { keyboardProps } = useKeyboard({
  onKeyDown: (e) => {
    switch(e.key) {
      case 'Delete':
        console.log('Удаление выбранного элемента');
        break;
      case 'Enter':
        console.log('Подтверждение действия');
        break;
    }
  }
});

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

Интеграция с другими хуками React Aria

useKeyboard хорошо сочетается с:

useFocus — для отслеживания и управления фокусом.
useSelectableCollection — для компонентов с выбором элементов через клавиатуру.
useMenu и useListBox — для создания доступных выпадающих списков.

Совместное использование позволяет создавать сложные интерактивные компоненты с минимальным количеством ручной логики.