re:re:actable
Урок 014 минуты чтения

Как спроектировать автокомплит (typeahead)

На этой странице
Кратко

Автокомплит — поле ввода, которое по мере набора показывает подсказки: поиск товаров, городов, пользователей. Это классическая задача на UI-компонент: важны API компонента, debounce запросов, отмена устаревших ответов (race condition), кеш результатов, навигация с клавиатуры и доступность по паттерну WAI-ARIA combobox, а также поведение на медленной сети и при ошибках.

Вопрос

Как спроектировать компонент автокомплита? Как избежать лишних запросов и гонок ответов, кешировать результаты и сделать компонент доступным?

R — требования

  • подсказки по мере ввода, выбор мышью и с клавиатуры;
  • источник — серверный API (большой объем данных) или локальный список;
  • подсветка совпадения, до 10 вариантов, состояния «загрузка», «ничего не найдено», «ошибка»;
  • нефункциональные: быстро (< 100 мс на ввод), не перегружать сервер, доступность, мобильные, переиспользуемость в разных местах.

A — архитектура

<Autocomplete>
 ├─ <input role="combobox">       ввод, клавиатура
 ├─ <Listbox role="listbox">      список вариантов (порталом поверх контента)
 │   └─ <Option role="option"> × N
 └─ controller (хук useAutocomplete)
       ├─ debounce ввода
       ├─ запрос через fetcher (+ AbortController)
       ├─ кеш: Map<query, results>
       └─ состояние: query, results, activeIndex, isOpen, status

Логику выносят в headless-хук, а разметку делает компонент — так поведение можно переиспользовать с другим UI.

D — модель данных

type Option<T> = { id: string; label: string; data: T };
 
type AutocompleteState<T> = {
  query: string;
  results: Option<T>[];
  activeIndex: number;            // -1 — ничего не выделено
  isOpen: boolean;
  status: "idle" | "loading" | "success" | "error";
};
 
const cache = new Map<string, Option<unknown>[]>();   // ключ — нормализованный запрос

I — интерфейс

API компонента:

<Autocomplete<City>
  fetchOptions={(query, signal) => api.searchCities(query, { signal })}
  onSelect={(city) => setCity(city)}
  minChars={2}
  debounceMs={250}
  renderOption={(option, { isActive, query }) => <Highlight text={option.label} query={query} />}
  placeholder="Город"
  label="Город доставки"
/>

API сервера:

GET /api/search/cities?q=моск&limit=10
→ { "items": [{ "id": "msk", "label": "Москва", "region": "..." }] }

O — оптимизации

Сеть и гонки:

useEffect(() => {
  if (query.length < minChars) return;
  const key = query.trim().toLowerCase();
  if (cache.has(key)) return setResults(cache.get(key)!);
 
  const controller = new AbortController();
  const timer = setTimeout(async () => {
    setStatus("loading");
    try {
      const items = await fetchOptions(key, controller.signal);
      cache.set(key, items);
      setResults(items);
      setStatus("success");
    } catch (e) {
      if ((e as Error).name !== "AbortError") setStatus("error");
    }
  }, debounceMs);
 
  return () => { clearTimeout(timer); controller.abort(); };   // новый ввод отменяет старый запрос
}, [query]);
  • debounce 200–300 мс сокращает запросы в разы;
  • AbortController или проверка «ответ для текущего query?» — ответ на «мо» не перезапишет «москва»;
  • кеш в памяти с ограничением размера (LRU) и TTL; повторный ввод «мос» после стирания — мгновенно;
  • minChars, ограничение limit;
  • для локальных данных — фильтрация в памяти, для очень больших — Web Worker или индекс (trie).

Доступность (combobox):

  • input: role="combobox", aria-expanded, aria-controls, aria-activedescendant, aria-autocomplete="list";
  • ul role="listbox", элементы role="option" с aria-selected;
  • стрелки — перемещение, Enter — выбор, Esc — закрыть, Tab — уйти без выбора;
  • фокус остается в поле; число результатов объявляется через aria-live.

UX:

  • подсветка совпадения без innerHTML (безопасно от XSS);
  • последние запросы и популярные варианты при пустом вводе;
  • позиционирование списка у края экрана (Floating UI), закрытие при клике вне;
  • на мобильных — полноэкранный режим поиска, inputMode, enterKeyHint="search".

Что важно помнить

  • Три главных темы, которые ждут на интервью: debounce, отмена/гонки, кеш.
  • isOpen и activeIndex сбрасываются при новом вводе и закрытии.
  • Компонент должен работать и в controlled-режиме (value + onChange), и uncontrolled.
  • Ошибка сети не должна ломать ввод — показываем строку ошибки внутри списка.
  • Связанные темы: debounce и throttle, отмена запросов.

Мини-шпаргалка

Headless-хук + разметка. debounce 200–300 мс, minChars, AbortController против гонок, LRU-кеш по нормализованному запросу. Combobox ARIA: aria-expanded, aria-activedescendant, listbox/option, стрелки/Enter/Esc. Состояния loading/empty/error, подсветка без innerHTML.

Документация

APG: Combobox Pattern, GreatFrontEnd: Front End System Design Playbook, Floating UI, MDN: AbortController.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам