Сигнатуры функций

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

Основные принципы сигнатур

  1. Аргументы функций всегда включают объект props, который содержит все свойства компонента, включая пользовательские и системные.
  2. Возвращаемое значение обычно представляет собой объект с набором атрибутов и методов для привязки к DOM-элементам.
  3. Состояние компонента часто передается через объекты состояния (state) из React Stately, которые используются вместе с React Aria для синхронизации состояния и UI.

Пример базовой сигнатуры функции:

function useButton(props, state, ref) {
  // props – свойства кнопки
  // state – состояние из React Stately
  // ref – ссылка на DOM-элемент
  return {
    buttonProps: {
      ...props,
      onClick: handleClick,
      'aria-label': props['aria-label']
    }
  };
}

Типичные функции React Aria

1. useButton

Сигнатура:

function useButton(
  props: AriaButtonProps,
  ref: RefObject<HTMLElement>
): { buttonProps: HTMLAttributes<HTMLElement> }
  • props — объект с атрибутами кнопки, включая onPress, isDisabled, aria-label.
  • ref — ссылка на реальный DOM-элемент.
  • Возвращаемое значение — объект с buttonProps, который нужно применять к элементу <button>.

Особенности:

  • Автоматическая обработка событий onClick, onPress.
  • Генерация правильных ARIA-атрибутов (aria-disabled, aria-pressed).
  • Интеграция с focusVisible для подсветки фокуса клавиатуры.

2. useCheckbox

Сигнатура:

function useCheckbox(
  props: AriaCheckboxProps,
  state: CheckboxState,
  ref: RefObject<HTMLInputElement>
): { inputProps: InputHTMLAttributes<HTMLInputElement> }
  • props — атрибуты чекбокса (isSelected, onChange, isDisabled).
  • state — состояние, содержащее текущее значение (checked или indeterminate) и методы для изменения.
  • ref — ссылка на <input type="checkbox">.
  • Возвращаемое значение — inputProps для применения к элементу.

Особенности:

  • Управление состоянием checked через объект state.
  • Генерация aria-checked с учетом частичных состояний (mixed).
  • Поддержка клавиатурной навигации и событий onKeyDown.

3. useMenu и useMenuItem

useMenu:

function useMenu(
  props: AriaMenuProps,
  state: MenuState,
  ref: RefObject<HTMLElement>
): { menuProps: HTMLAttributes<HTMLElement> }

useMenuItem:

function useMenuItem(
  props: AriaMenuItemProps,
  state: MenuState,
  ref: RefObject<HTMLElement>
): { menuItemProps: HTMLAttributes<HTMLElement> }
  • props — свойства меню/элемента меню (key, isDisabled, onAction).
  • state — объект состояния меню, который управляет текущим выделением и открытием/закрытием.
  • ref — ссылка на DOM-элемент.
  • Возвращаемое значение — набор ARIA-атрибутов для корректного взаимодействия с экранными читалками.

Особенности:

  • useMenu управляет навигацией по элементам с клавиатуры.
  • useMenuItem автоматически добавляет атрибуты role="menuitem" и aria-disabled.
  • Поддержка вложенных меню через useMenuSection.

Общая структура сигнатур

Все функции React Aria следуют единому паттерну:

useX(props, state?, ref?) => {
  ...propsForDOM
}
  • props — обязательный объект с параметрами компонента.
  • state — опциональный объект состояния, если компонент управляет выбором или переключением.
  • ref — опциональная ссылка на DOM-элемент для корректной работы фокуса и событий.
  • Возвращаемый объект содержит набор props и методов для привязки к DOM.

Советы по работе с сигнатурами

  • Типизация. Использовать TypeScript для строгой типизации аргументов и возвращаемых значений.
  • Композиция функций. Многие хук-функции React Aria можно комбинировать, например useButton + useFocusRing, чтобы добавить визуальный фокус.
  • Состояние через React Stately. Отделять логику состояния от логики UI позволяет легко создавать сложные компоненты с переключением, чекбоксами, меню и списками.
  • Передача ref. Всегда передавать ref в возвращаемые функции для корректного управления фокусом и клавиатурной навигацией.
  • ARIA-атрибуты. Никогда не применять их вручную, если есть соответствующий хук — библиотека гарантирует правильное соответствие спецификации.

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

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

function AccessibleButton(props) {
  const ref = useRef(null);
  const { buttonProps } = useButton(props, ref);
  const { focusProps, isFocusVisible } = useFocusRing();

  return (
    <button
      {...buttonProps}
      {...focusProps}
      ref={ref}
      style={{
        outline: isFocusVisible ? '2px solid blue' : 'none'
      }}
    >
      {props.children}
    </button>
  );
}
  • Сигнатура функции useButton обеспечивает корректное управление событиями.
  • useFocusRing добавляет визуальную подсветку фокуса.
  • Объединение props позволяет полностью контролировать поведение и доступность элемента.

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

Оглавление