Класс awesomplete

Класс Awesomplete представляет собой конструктор, реализующий механизм автодополнения для текстовых полей ввода. Архитектура построена вокруг расширяемого экземпляра, который связывается с DOM-элементом <input> и динамически управляет списком подсказок, их фильтрацией, отображением и выбором.

Инициализация экземпляра выполняется через new Awesomplete(input, options).

Сигнатура:

new Awesomplete(input, options)

Параметры конструктора

input DOM-элемент <input>, к которому привязывается логика автодополнения. Элемент становится источником пользовательского ввода и точкой взаимодействия с подсказками.

options — объект конфигурации:

  • list — массив значений или функция, возвращающая список подсказок.
  • minChars — минимальное количество символов для активации списка (по умолчанию 1).
  • maxItems — максимальное число отображаемых элементов.
  • autoFirst — автоматический выбор первого элемента списка.
  • filter — функция фильтрации элементов.
  • sort — функция сортировки результатов.
  • item — шаблон генерации DOM-элемента списка.
  • replace — функция подстановки выбранного значения в input.
  • data — функция извлечения значения из объекта списка.

Внутренняя структура экземпляра

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

input

Ссылка на связанный DOM-элемент. Используется для чтения и записи значения, а также для отслеживания событий input, keydown, blur.

ul

DOM-элемент списка подсказок (<ul>), создаваемый автоматически. В него помещаются элементы <li>.

selected

Индекс текущего выбранного элемента списка. Значение -1 означает отсутствие активного выбора.

index

Текущий индекс навигации по списку. Используется при перемещении стрелками клавиатуры.

opened

Булево состояние отображения списка. Определяет, открыт ли выпадающий блок подсказок.

Основные методы класса

open()

Открывает список подсказок и делает его видимым. При вызове выполняется построение DOM-структуры элементов на основе текущего списка list.

awesomplete.open();

Поведение:

  • создаётся или активируется ul
  • применяется фильтрация данных
  • рендерятся элементы списка
  • устанавливается состояние opened = true

close()

Закрывает список и скрывает его из DOM-видимости.

awesomplete.close();

При выполнении:

  • очищается активный индекс
  • сбрасывается состояние навигации
  • opened устанавливается в false

next()

Перемещает активный индекс на следующий элемент списка.

awesomplete.next();

Если достигнут конец списка, происходит циклический переход к началу.

previous()

Перемещает активный индекс на предыдущий элемент.

awesomplete.previous();

При достижении начала списка происходит переход к последнему элементу.

goto(i)

Устанавливает активный индекс на конкретное значение.

awesomplete.goto(2);

Используется для программного управления навигацией.

select()

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

awesomplete.select();

Алгоритм:

  • извлечение значения через data()
  • преобразование через replace()
  • запись в input.value
  • закрытие списка

evaluate()

Ключевой метод пересчёта и отображения списка.

awesomplete.evaluate();

Функциональность:

  • чтение текущего значения input
  • фильтрация list
  • сортировка результатов
  • ограничение по maxItems
  • обновление DOM-элементов
  • управление состоянием opened

Событийная модель

Awesomplete не использует сложную систему событий, но опирается на стандартные DOM-события и внутренние колбэки.

input-события

Основное событие — input:

  • инициирует evaluate()
  • проверяет minChars
  • обновляет список

keydown-события

Обрабатываются следующие клавиши:

  • ArrowDown — переход к следующему элементу
  • ArrowUp — переход к предыдущему
  • Enter — выбор текущего элемента
  • Escape — закрытие списка

blur-событие

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

Фильтрация и сортировка

filter(item, input)

Функция определяет, попадает ли элемент в результат.

Типовая реализация:

filter: function (text, input) {
  return RegExp(input, "i").test(text);
}

Фильтрация выполняется на каждом вводе символа.

sort(a, b)

Функция сортировки определяет порядок отображения.

По умолчанию реализуется лексикографическое сравнение или приоритет совпадений в начале строки.

Шаблоны элементов списка

item(text, input)

Определяет структуру <li>.

item: function(text, input) {
  return Awesomplete.$("li", {
    innerHTML: text.replace(RegExp(input, "gi"), "<mark>$&</mark>")
  });
}

Элемент может включать подсветку совпадений через <mark>.

replace(text)

Определяет, как значение вставляется в input.

replace: function(text) {
  this.input.value = text;
}

Возможны модификации, включая форматирование, обрезку или добавление префиксов/суффиксов.

Работа с источниками данных

Статический массив

new Awesomplete(input, {
  list: ["Apple", "Apricot", "Banana"]
});

Объектный список

list: [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" }
]

Для объектов используется data():

data: function(item) {
  return item.value;
}

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

Состояние контролируется через комбинацию свойств:

  • opened — видимость
  • selected — выбранный элемент
  • index — текущая позиция

Изменение состояния синхронизируется с DOM в реальном времени, без необходимости ручного рендера.

Взаимодействие с DOM

Awesomplete создает и управляет следующими элементами:

  • контейнер списка <ul>

  • элементы подсказок <li>

  • классы состояния:

    • awesomplete
    • active
    • selected

Добавление классов происходит динамически при навигации и выборе элементов.

Расширяемость класса

Архитектура допускает переопределение всех ключевых методов:

  • filter
  • sort
  • item
  • replace
  • data

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

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

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

list: function() {
  return fetch("/api/suggest")
    .then(res => res.json());
}

При этом evaluate() ожидает результат перед построением списка.

Внутренний алгоритм работы

Цикл обработки ввода включает последовательные этапы:

  1. Считывание значения input
  2. Проверка минимальной длины
  3. Получение списка источников
  4. Фильтрация элементов
  5. Сортировка результатов
  6. Ограничение количества
  7. Рендеринг DOM
  8. Активация списка

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

Оглавление