Параметр autoFirst

Параметр autoFirst в библиотеке Awesomplete управляет автоматическим выделением первого элемента списка подсказок при открытии выпадающего меню. Это один из ключевых элементов настройки UX автодополнения, так как он напрямую влияет на скорость выбора и поведение клавиатурной навигации.

Назначение autoFirst

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

При включённом autoFirst:

  • первый элемент списка автоматически становится активным;
  • пользователь может сразу подтвердить выбор клавишей Enter;
  • уменьшается количество действий при выборе наиболее вероятного варианта.

При выключенном autoFirst:

  • ни один элемент не выделяется при открытии списка;
  • пользователь обязан вручную переместить фокус стрелками;
  • поведение становится более «нейтральным» и предсказуемым в сценариях с неоднозначными данными.

Синтаксис и подключение

Параметр задаётся при инициализации экземпляра Awesomplete:

new Awesomplete(inputElement, {
    list: ["Apple", "Apricot", "Avocado"],
    autoFirst: true
});

По умолчанию значение параметра — false.

Поведение при autoFirst: true

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

Механика работы

  1. Формируется список совпадений.
  2. После рендера выпадающего меню первый элемент получает состояние aria-selected и внутренний CSS-класс активности.
  3. Клавиша Enter сразу подтверждает этот элемент без дополнительной навигации.

Пример поведения

Если список содержит:

Apple
Apricot
Avocado

то при вводе запроса и открытии списка:

  • активным становится Apple;
  • нажатие Enter сразу выбирает Apple;
  • стрелки вверх/вниз изменяют активный элемент относительно первого.

Поведение при autoFirst: false

В выключенном режиме:

  • список отображается без активного элемента;
  • первый Enter может не приводить к выбору, если не было явного наведения;
  • навигация стрелками требуется для установки текущего элемента.

Это поведение ближе к классическим dropdown-компонентам, где выбор всегда является явным действием пользователя.

Влияние на UX

Сценарии, где autoFirst: true полезен

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

Сценарии, где autoFirst: false предпочтительнее

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

Взаимодействие с фильтрацией списка

autoFirst работает поверх механизма фильтрации данных. Это означает, что:

  • сначала применяется фильтр совпадений;
  • затем определяется первый элемент уже отфильтрованного массива;
  • активный элемент всегда соответствует текущему порядку отображения.

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

Особенности работы с динамическими списками

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

awesomplete.list = ["Banana", "Blueberry", "Blackberry"];

поведение autoFirst сохраняется:

  • новый список пересчитывается;
  • первый элемент нового набора становится активным (при включённом параметре);
  • предыдущие состояния не сохраняются.

Это важно при работе с AJAX или асинхронной подгрузкой данных.

Сочетание с клавиатурной навигацией

Клавиши управления ведут себя по-разному в зависимости от состояния autoFirst:

  • Arrow Down: при включённом autoFirst перемещает выделение со второго элемента; при выключенном — с нулевой позиции.
  • Enter: при включённом autoFirst сразу подтверждает первый элемент; при выключенном требует предварительного выбора.
  • Escape: закрывает список независимо от состояния.

Влияние на доступность (ARIA)

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

При autoFirst: true:

  • первый элемент получает aria-selected="true";
  • экранные читалки воспринимают его как текущий выбор по умолчанию.

При autoFirst: false:

  • ни один элемент не помечается как выбранный при открытии;
  • выбор фиксируется только после явного действия пользователя.

Потенциальные ошибки при использовании

Неправильное понимание поведения autoFirst часто приводит к логическим ошибкам в интерфейсе:

  • ожидание, что Enter всегда требует подтверждения выбора;
  • конфликт между визуальным выделением и логикой формы;
  • неожиданный выбор первого элемента в длинных списках.

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

Совместимость с кастомными списками

При использовании объектов вместо строк:

new Awesomplete(input, {
    list: [
        { label: "USA", value: "US" },
        { label: "Ukraine", value: "UA" }
    ],
    autoFirst: true
});

логика остаётся неизменной:

  • активируется первый объект;
  • отображается label;
  • возвращается value.

Поведение при пустых и коротких списках

Если список содержит:

  • 0 элементов — autoFirst не имеет эффекта;
  • 1 элемент — он автоматически становится активным при любом значении параметра;
  • 2+ элементов — применяется стандартная логика выбора первого.

Производительность и внутренняя логика

Параметр не влияет на скорость фильтрации напрямую, однако добавляет шаг установки активного элемента после каждого обновления списка.

Внутренне это:

  • минимальная операция DOM-обновления;
  • присвоение состояния первому элементу;
  • синхронизация с текущим индексом навигации.

На практике влияние на производительность отсутствует даже при больших списках.

Поведение в комбинации с другими настройками

autoFirst часто используется вместе с:

  • minChars — чтобы активировать первый элемент только после достаточного ввода;
  • maxItems — ограничение количества отображаемых подсказок усиливает эффект первого элемента;
  • filter — влияет на то, какой элемент станет первым после сортировки;
  • sort — напрямую определяет, какой элемент окажется на позиции №1.

Именно комбинация sort + autoFirst формирует итоговое поведение автоподстановки.

Оглавление