useSearchField для поиска

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

Хук возвращает два основных объекта: searchFieldProps и labelProps. Первый используется для непосредственного применения к <input> поля поиска, второй — для корректного связывания с <label>.

import { useSearchField } from '@react-aria/searchfield';
import { useSearchFieldState } from '@react-stately/searchfield';
import { useRef } from 'react';

function Search() {
  const ref = useRef();
  const state = useSearchFieldState({ defaultValue: '' });
  const { searchFieldProps, labelProps } = useSearchField({ placeholder: 'Поиск...' }, state, ref);

  return (
    <div>
      <label {...labelProps}>Поиск</label>
      <input {...searchFieldProps} ref={ref} />
    </div>
  );
}

Параметры и конфигурация

useSearchField принимает три аргумента: props, state и ref.

Props поддерживает следующие ключевые свойства:

  • placeholder — текст-заполнитель для поля ввода.
  • isDisabled — флаг, который отключает поле поиска.
  • isReadOnly — делает поле только для чтения.
  • autoFocus — автоматически фокусирует поле при рендере.
  • onSubmit — функция обратного вызова при отправке запроса.

State создается с помощью useSearchFieldState из React Stately и управляет внутренним значением поля, включая очистку и отправку данных.

Ref необходим для привязки хука к DOM-элементу и обеспечения корректной работы доступности.

const state = useSearchFieldState({
  defaultValue: '',
  onSubmit: (value) => console.log('Поиск:', value)
});

Доступность и роли

useSearchField автоматически добавляет все необходимые ARIA-атрибуты:

  • role="search" для контейнера.
  • aria-label или aria-labelledby для привязки к <label>.
  • Обеспечивает поддержку клавиш Enter для отправки и Escape для очистки.

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

<div role="search">
  <label {...labelProps}>Поиск</label>
  <input {...searchFieldProps} ref={ref} />
</div>

Управление состоянием поиска

useSearchFieldState предоставляет следующие свойства и методы:

  • value — текущее значение поля.
  • setValue(newValue) — обновление значения вручную.
  • clear() — очистка поля.
  • submit() — принудительная отправка текущего значения.

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

function handleClear() {
  state.clear();
}

function handleSubmit() {
  state.submit();
}

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

useSearchField легко комбинируется с любыми библиотеками компонентов, такими как Chakra UI или Material UI, обеспечивая:

  • Сохранение доступности при кастомном рендере.
  • Возможность добавления кнопок очистки и иконок поиска.
  • Совместимость с автозаполнением и подсказками.

Пример с кастомной кнопкой очистки:

<div role="search" style={{ position: 'relative' }}>
  <input {...searchFieldProps} ref={ref} />
  {state.value && (
    <button onCl ick={() => state.clear()} aria-label="Очистить поиск">
      ×
    </button>
  )}
</div>

События и обработка взаимодействия

Хук обеспечивает корректную работу с основными событиями:

  • onChange — обновление значения при вводе.
  • onSubmit — вызов при нажатии Enter.
  • onFocus/onBlur — управление фокусом и внешним видом компонента.

Эта структура делает useSearchField универсальным инструментом для создания сложных и доступных поисковых интерфейсов, одновременно сокращая количество ручного кода для работы с ARIA.

Поддержка клавиатуры

Все элементы, созданные с использованием useSearchField, автоматически поддерживают стандартные сценарии клавиатуры:

  • Enter — отправка запроса.
  • Escape — очистка поля.
  • Tab — переход к следующему элементу формы.

Это позволяет пользователям работать с полем поиска без мыши, соблюдая принципы WCAG.

useSearchField в связке с useSearchFieldState и кастомными компонентами предоставляет полный набор инструментов для создания доступного, интерактивного и легко настраиваемого поля поиска в React-приложениях.

Оглавление