useField для полей ввода

Хук useField предназначен для управления состоянием и поведением полей ввода в приложениях на React, обеспечивая соответствие стандартам доступности (ARIA). Он является частью библиотеки React Aria и используется совместно с компонентами управления формами, обеспечивая корректную работу с метками, подсказками, ошибками и фокусом.

useField инкапсулирует логику, которая в обычных условиях требовала бы ручной настройки атрибутов id, aria-labelledby, aria-describedby и управления состоянием ошибок и валидации.

Основные возможности

  1. Согласованное управление идентификаторами Хук автоматически генерирует уникальные идентификаторы для:

    • метки (label)
    • подсказки (description)
    • сообщения об ошибке (errorMessage)

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

  2. Поддержка состояний валидации Через useField можно передавать статус валидации (errorMessage, isRequired, validationState). Хук добавляет соответствующие атрибуты:

    • aria-invalid при наличии ошибки
    • aria-required для обязательных полей
    • aria-describedby для подсказок и сообщений об ошибках

  3. Совместимость с формами Хук интегрируется с формами React Aria, обеспечивая единое управление фокусом и состояниями ввода, что особенно важно для комплексных интерфейсов.

Сигнатура хука

const { labelProps, inputProps, descriptionProps, errorMessageProps } = useField(props);

Параметры props:

  • name — имя поля формы
  • label — текст метки
  • description — текст подсказки
  • errorMessage — текст ошибки
  • isRequired — флаг обязательного поля
  • validationState — valid | invalid | none

Возвращаемые значения:

  • labelProps — props для элемента <label>
  • inputProps — props для самого поля ввода
  • descriptionProps — props для описания или подсказки
  • errorMessageProps — props для сообщения об ошибке

Эти props включают автоматически сгенерированные id и ARIA-атрибуты, обеспечивая полное соответствие стандартам доступности.

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

import { useField } from "@react-aria/fields";
import { useTextField } from "@react-aria/textfield";

function TextInput({ label, description, errorMessage, isRequired }) {
  const { labelProps, inputProps, descriptionProps, errorMessageProps } = useField({
    label,
    description,
    errorMessage,
    isRequired,
    validationState: errorMessage ? 'invalid' : 'valid'
  });

  const { inputProps: textInputProps } = useTextField(inputProps);

  return (
    <div>
      <label {...labelProps}>{label}</label>
      <input {...textInputProps} />
      {description && <div {...descriptionProps}>{description}</div>}
      {errorMessage && <div {...errorMessageProps}>{errorMessage}</div>}
    </div>
  );
}

В этом примере useField управляет:

  • генерацией id для метки, описания и ошибки
  • установкой aria-describedby на поле ввода, связывая его с подсказкой и ошибкой
  • добавлением aria-invalid и aria-required

Использование useTextField совместно с useField гарантирует корректное поведение фокуса и поддержку нативных событий ввода.

Интеграция с кастомными компонентами

useField позволяет легко строить кастомные поля ввода, будь то текстовые поля, textarea или комбинированные компоненты, при этом сохраняя доступность:

function CustomInput({ label, description, errorMessage, isRequired }) {
  const { labelProps, inputProps, descriptionProps, errorMessageProps } = useField({
    label,
    description,
    errorMessage,
    isRequired
  });

  return (
    <div className="custom-input">
      <span {...labelProps}>{label}</span>
      <div className="input-wrapper">
        <input {...inputProps} />
      </div>
      {description && <small {...descriptionProps}>{description}</small>}
      {errorMessage && <small {...errorMessageProps}>{errorMessage}</small>}
    </div>
  );
}

Важно, что даже при нестандартной разметке useField корректно связывает все элементы через ARIA и поддерживает работу скринридеров.

Передача состояния валидации

С помощью параметра validationState можно управлять состоянием поля:

  • 'valid' — поле валидно
  • 'invalid' — поле содержит ошибку
  • 'none' — нейтральное состояние
const { inputProps } = useField({
  label: "Email",
  errorMessage: emailError,
  validationState: emailError ? 'invalid' : 'valid'
});

При этом aria-invalid будет автоматически установлен в true при наличии ошибки.

Лучшие практики

  1. Использовать useField вместе с соответствующими хуками ввода, например useTextField, useCheckbox, useSelect для комплексных форм.
  2. Не дублировать id вручную — хук гарантирует уникальность идентификаторов.
  3. Стараться передавать description и errorMessage для максимальной доступности интерфейса.
  4. Использовать validationState вместо ручного управления aria-invalid, чтобы исключить ошибки при синхронизации состояния.
  5. Комбинировать с кастомной разметкой — useField корректно работает даже при обертывании поля в дополнительные контейнеры.

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

Оглавление