Метод select

Метод select в Awesomplete отвечает за программный выбор элемента из списка подсказок и имитацию пользовательского клика по нему. Он является центральной точкой завершения цикла автодополнения: от отображения списка вариантов до фиксации выбранного значения в поле ввода и вызова связанных обработчиков событий.

Внутренний механизм Awesomplete строится вокруг списка сгенерированных вариантов и текущего активного элемента. Когда происходит выбор, необходимо синхронизировать сразу несколько состояний:

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

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

Сигнатура и параметры

Типичная сигнатура метода в контексте Awesomplete выглядит следующим образом:

select(item, originalEvent)

Параметры:

  • item — объект или элемент списка подсказок, который должен быть выбран. Обычно это объект вида { label, value }, либо DOM-элемент, в зависимости от конфигурации данных.
  • originalEvent — необязательное событие, вызвавшее выбор (например, click или keydown). Используется для передачи контекста в пользовательские обработчики и для корректного поведения отмены.

Внутренний процесс выбора

При вызове select библиотека выполняет последовательность действий, которая условно делится на несколько этапов.

1. Определение выбранного значения

Из объекта item извлекается отображаемое значение. Обычно используется поле value или label, в зависимости от структуры данных:

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

Результат становится финальным значением, которое будет установлено в input.

2. Обновление поля ввода

После определения значения происходит запись в input-элемент:

this.input.value = selectedValue;

Этот шаг синхронизирует UI с выбранной подсказкой и завершает визуальное состояние автодополнения.

3. Вызов события select

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

  • select
  • с передачей выбранного элемента
  • и оригинального события (если оно было)

Пример логики:

this._dispatch("select", {
    text: item,
    originalEvent: originalEvent
});

Если обработчик возвращает явное значение false, выбор может быть отменён, а значение input не изменено. Это позволяет реализовывать контроль над логикой выбора на уровне приложения.

4. Закрытие списка

После успешного выбора список подсказок скрывается. Это необходимо для предотвращения повторного взаимодействия с устаревшими данными.

Внутренне это эквивалентно вызову метода закрытия, аналогичного close():

  • очищается активный индекс;
  • скрывается контейнер списка;
  • снимаются ARIA-атрибуты состояния.

5. Сброс состояния навигации

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

  • индекс сбрасывается;
  • состояние “highlighted” удаляется;
  • список переводится в неактивное состояние.

Это предотвращает повторный выбор устаревшего элемента при следующем открытии списка.

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

Если originalEvent не передан, метод работает в программном режиме. Это означает:

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

Такой режим используется при интеграции с внешними API или при автоматическом заполнении формы.

Отличие от вспомогательных методов

Метод select часто сравнивается с другими внутренними функциями Awesomplete, однако его роль строго определена.

Отличие от replace

replace обычно отвечает только за подстановку значения в input без полной логики завершения выбора. В отличие от него:

  • select завершает цикл взаимодействия;
  • вызывает события;
  • закрывает список;
  • сбрасывает состояние.

Отличие от evaluate

evaluate отвечает за построение списка подсказок, а не за выбор. Это противоположные этапы:

  • evaluate генерирует список;
  • select фиксирует один элемент.

Использование в пользовательских сценариях

Метод активно используется при расширении поведения автодополнения. На уровне интеграции он может быть вызван при:

  • обработке кастомных клавиш;
  • реализации альтернативного UI (например, внешнего списка);
  • синхронизации с серверным выбором;
  • автоматическом выборе первого элемента.

Пример программного вызова:

awesomplete.select(awesomplete.suggestions[0]);

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

Работа с клавиатурной навигацией

Метод select тесно связан с обработкой клавиш Enter и Tab. При нажатии этих клавиш:

  • определяется активный элемент списка;
  • вызывается select;
  • событие клавиатуры передаётся как originalEvent.

Таким образом обеспечивается единообразие поведения между кликами мыши и клавиатурным выбором.

Обработка пользовательских событий

При использовании событий Awesomplete важно учитывать порядок вызовов:

  1. формирование списка (evaluate);
  2. отображение подсказок;
  3. навигация по элементам;
  4. выбор (select);
  5. закрытие списка.

Событие select является точкой, в которой можно вмешаться в финальное значение. При возврате false из обработчика поведение может быть изменено:

input.addEventListener("awesomplete-select", function(event) {
    if (event.text.value === "blocked") {
        return false;
    }
});

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

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

При использовании нестандартных источников данных item может быть не просто объектом, а структурой, возвращаемой внешним API. В таких случаях select опирается на внутреннюю нормализацию:

  • извлечение отображаемого текста;
  • определение значения для input;
  • сохранение оригинального объекта в событии.

Это важно для сценариев, где значение для пользователя и значение для логики приложения различаются.

Состояние компонента после выполнения select

После завершения метода состояние Awesomplete становится полностью сброшенным:

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

Это делает компонент готовым к следующему циклу ввода без дополнительных действий.

Взаимодействие с accessibility (ARIA)

При вызове select обновляются ARIA-атрибуты:

  • aria-expanded устанавливается в false;
  • aria-activedescendant очищается;
  • состояние списка становится неактивным для скринридеров.

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

Ключевые особенности метода

Метод select можно рассматривать как точку фиксации результата автодополнения:

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