Параметры и опции

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

Общая структура параметров

Каждый хук в React Aria принимает объект параметров, который определяет:

  • Тип и роль элемента — через свойство role или специализированные ключи (например, selectionMode для списков или orientation для табов).
  • Состояние компонента — свойства вроде isDisabled, isSelected, isOpen, isReadOnly управляют доступностью и визуальным состоянием.
  • Обработчики событий — через свойства, начинающиеся с on (onFocus, onKeyDown, onOpenChange), которые позволяют перехватывать пользовательские действия.
  • Атрибуты ARIA — React Aria автоматически вычисляет нужные атрибуты на основе переданных параметров, что упрощает поддержку доступности.

Пример базового использования:

import {useButton} from '@react-aria/button';
import {useRef} from 'react';

function MyButton({onPress, isDisabled}) {
  let ref = useRef();
  let {buttonProps} = useButton({onPress, isDisabled}, ref);

  return <button {...buttonProps} ref={ref}>Нажми меня</button>;
}

В этом примере объект {onPress, isDisabled} является параметром, который управляет поведением кнопки и автоматически формирует правильные ARIA-атрибуты.

Параметры для управления состоянием

isDisabled Устанавливает состояние недоступности элемента. Компонент при этом корректно обновляет aria-disabled и предотвращает взаимодействие пользователя.

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

isSelected Отмечает элемент как выбранный. В сочетании с хранилищем состояния React Aria (useSelectionState) позволяет управлять выделением элементов в списках или таблицах.

isOpen / defaultOpen Управляет открытием и закрытием всплывающих элементов, таких как меню или календари. Отличие isOpen от defaultOpen в том, что первый параметр контролируемый, а второй задаёт начальное состояние.

Параметры взаимодействия

onFocus / onBlur Позволяют отследить получение и потерю фокуса. React Aria автоматически учитывает фокус для клавиатурной навигации и корректно применяет атрибуты aria-activedescendant.

onKeyDown / onKeyUp Используются для перехвата клавиш. В большинстве хуков библиотеки уже реализованы стандартные комбинации, соответствующие ARIA-спецификациям, но эти обработчики позволяют добавлять кастомную логику.

onOpenChange Специфический параметр для всплывающих элементов (меню, селекторы). Передаёт текущее состояние открытости и позволяет синхронизировать его с внешним состоянием приложения.

Параметры навигации и выбора

selectionMode Задаёт тип выбора в коллекциях: 'single', 'multiple' или 'none'. В сочетании с useSelectionState позволяет реализовать управляемый или неуправляемый выбор элементов списка или таблицы.

disallowEmptySelection Флаг, который запрещает оставлять коллекцию без выделенных элементов. Работает только в режиме 'single' или 'multiple'.

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

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

Параметры визуализации и ориентации

orientation Принимает 'horizontal' или 'vertical'. Используется в компонентах вроде табов, разделителей и панелей, чтобы корректно обрабатывать клавиатурную навигацию (ArrowLeft/ArrowRight для горизонтальных, ArrowUp/ArrowDown для вертикальных).

shouldFlip Для всплывающих элементов определяет, можно ли автоматически менять направление рендера (например, всплывающее меню может открываться вверх, если снизу нет места).

isQuiet / isEmphasized Эстетические параметры для кнопок и других элементов управления, влияющие на визуальный стиль, но не нарушающие доступность.

Специальные параметры хуков

Некоторые хуки React Aria предоставляют дополнительные, специфические параметры:

  • useMenu — onAction, onClose для обработки выбора элемента и закрытия меню.
  • useSlider — minValue, maxValue, step, isReversed для точного управления ползунком.
  • useDialog — isDismissable, onClose для контроля закрытия модального окна.
  • useComboBox — defaultItems, allowsCustomValue, onInputChange для автозаполнения и фильтрации.

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

Передача параметров через ref и props

Большинство хуков React Aria используют комбинацию:

  • Ref элемента — передаётся вторым аргументом и нужен для управления фокусом и обработкой событий.
  • Props объекта — возвращаемый объект (buttonProps, menuProps, listBoxProps) объединяет все необходимые ARIA-атрибуты и обработчики событий.

Использование spread-оператора гарантирует корректное применение всех параметров:

let {menuProps} = useMenu({onAction}, menuRef);
return <ul {...menuProps} ref={menuRef}>...</ul>;

Такой подход упрощает интеграцию с любыми визуальными библиотеками и кастомными компонентами, сохраняя доступность «из коробки».

Итоговая схема параметров

  1. Состояние — isDisabled, isReadOnly, isSelected, isOpen.
  2. Взаимодействие — onFocus, onBlur, onKeyDown, onOpenChange.
  3. Выбор и навигация — selectionMode, disallowEmptySelection, shouldFocusWrap.
  4. Визуальные и ориентационные — orientation, shouldFlip, isQuiet, isEmphasized.
  5. Специфические для хуков — уникальные параметры, влияющие на поведение отдельных компонентов.

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

Оглавление