Событие awesomplete-select

Событие awesomplete-select является ключевым механизмом взаимодействия с библиотекой Awesomplete, отвечающей за автодополнение в текстовых полях. Оно возникает в момент выбора пользователем элемента из списка подсказок, но до финального применения значения к полю ввода, что позволяет перехватывать, анализировать и модифицировать поведение выбора.

Автодополнение в Awesomplete проходит несколько стадий:

  1. Пользователь вводит текст в поле ввода.
  2. Выполняется фильтрация данных и формируется список подсказок.
  3. Отображается выпадающий список.
  4. Пользователь выбирает элемент (клавиатурой или мышью).
  5. Срабатывает awesomplete-select.
  6. После него может последовать применение значения и дополнительные события.

Событие awesomplete-select фиксирует именно момент выбора элемента, но до окончательной подстановки текста в input. Это делает его важным для валидации, преобразования данных и управления логикой выбора.

Механика возникновения события

Событие создаётся как CustomEvent и диспатчится экземпляром Awesomplete, привязанным к конкретному input-элементу. Оно содержит объект с дополнительной информацией о выбранном элементе.

Типичная структура события:

  • type: "awesomplete-select"

  • detail: объект с данными выбора

    • selected: DOM-элемент или объект списка
    • text: отображаемый текст
    • value: значение, которое может быть записано в input
    • index: индекс выбранного элемента в списке

Подписка на событие

Обработка выбора осуществляется через стандартный механизм событий DOM:

input.addEventListener("awesomplete-select", function(event) {
    console.log(event.detail);
});

В данном случае input — HTMLInputElement, к которому привязана логика Awesomplete. Событие срабатывает на этом же элементе, что позволяет централизованно управлять поведением автодополнения.

Структура объекта event.detail

Наиболее важной частью события является detail, содержащий информацию о выбранной записи.

Основные поля detail

selected Ссылка на выбранный элемент данных. В зависимости от конфигурации Awesomplete это может быть строка или объект.

text Текст, который отображается в выпадающем списке. Используется для UI-отображения и логики подсветки.

value Фактическое значение, предназначенное для вставки в input. Может отличаться от text при использовании сложных структур данных.

index Позиция выбранного элемента в массиве suggestions.

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

awesomplete-select позволяет вмешиваться в процесс до того, как значение окажется в поле ввода. Это даёт возможность:

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

Пример простой валидации:

input.addEventListener("awesomplete-select", function(event) {
    if (event.detail.value.startsWith("#")) {
        console.warn("Запрещённый формат значения");
        event.preventDefault();
    }
});

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

Модификация выбранного значения

Одной из частых задач является преобразование выбранного элемента перед записью в input.

input.addEventListener("awesomplete-select", function(event) {
    const value = event.detail.value;

    event.detail.value = value.toUpperCase();
});

Такая модификация полезна при нормализации данных: приведение к верхнему регистру, добавление префиксов, форматирование идентификаторов.

Отличие от awesomplete-selectcomplete

В Awesomplete существует близкое событие awesomplete-selectcomplete, которое срабатывает позже — после завершения процесса установки значения в input.

Различие можно выразить следующим образом:

  • awesomplete-select — момент выбора, до финальной записи значения;
  • awesomplete-selectcomplete — момент после завершения обновления поля.

Это различие критично при необходимости вмешательства в процесс:

  • если требуется изменить данные — используется awesomplete-select;
  • если требуется реагировать на уже установленное значение — используется awesomplete-selectcomplete.

Предотвращение стандартного поведения

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

input.addEventListener("awesomplete-select", function(event) {
    const allowed = checkPermission(event.detail.value);

    if (!allowed) {
        event.preventDefault();
    }
});

При вызове preventDefault() Awesomplete отменяет установку значения в input, сохраняя текущее состояние без изменений.

Использование с кастомными списками

При работе с массивами объектов Awesomplete часто используется структура:

new Awesomplete(input, {
    list: [
        { label: "Москва", value: "moscow" },
        { label: "Санкт-Петербург", value: "spb" }
    ]
});

В этом случае awesomplete-select позволяет точно контролировать, какое значение будет использовано.

input.addEventListener("awesomplete-select", function(event) {
    console.log(event.detail.label);
    console.log(event.detail.value);
});

Такая модель разделяет отображаемое и фактическое значение, что важно для интернационализации и работы с идентификаторами.

Интеграция с внешним состоянием

Событие часто используется в связке с state-менеджментом или реактивными системами.

input.addEventListener("awesomplete-select", function(event) {
    appState.selectedCity = event.detail.value;
});

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

Обработка сложных сценариев выбора

В реальных приложениях выбор элемента может запускать дополнительные процессы:

  • загрузку данных;
  • переход по маршрутам;
  • обновление зависимых полей формы;
  • вызов API.
input.addEventListener("awesomplete-select", function(event) {
    fetch(`/api/info?value=${event.detail.value}`)
        .then(res => res.json())
        .then(data => {
            updateUI(data);
        });
});

Такое использование делает awesomplete-select точкой интеграции между UI и бизнес-логикой.

Поведение при выборе клавиатурой и мышью

Событие не зависит от способа выбора элемента. Оно одинаково срабатывает:

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

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

Особенности распространения события

awesomplete-select не является нативным DOM-событием браузера, поэтому:

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

Практика безопасной обработки

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

  • проверять наличие полей перед использованием;
  • не полагаться на жёсткую типизацию без проверки;
  • обрабатывать случаи отсутствия value или text.
input.addEventListener("awesomplete-select", function(event) {
    const detail = event.detail || {};

    if (!detail.value) return;

    process(detail.value);
});

Такой подход снижает риск ошибок при нестандартных данных или кастомных источниках списка.

Комбинирование с другими событиями Awesomplete

awesomplete-select часто используется вместе с другими событиями:

  • awesomplete-open
  • awesomplete-close
  • awesomplete-selectcomplete

Комбинация позволяет построить полный контроль над жизненным циклом автодополнения, включая открытие списка, выбор элемента и завершение обработки.

Оглавление