Полный список параметров

Инициализация Awesomplete строится вокруг передачи второго аргумента конструктора — объекта конфигурации. Именно этот объект определяет поведение автодополнения, способ фильтрации, формат элементов списка и реакцию на ввод пользователя.

Основная форма:

new Awesomplete(inputElement, {
    list: [],
    minChars: 1,
    maxItems: 10,
    autoFirst: false,
    sort: ...,
    filter: ...,
    item: ...,
    replace: ...
});

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

list — источник данных для автодополнения

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

Массив строк

Базовый вариант:

list: ["Apple", "Apricot", "Avocado"]

Каждая строка рассматривается как отдельный элемент.

Массив объектов

Используется при необходимости хранить дополнительные данные:

list: [
  { label: "Apple", value: "apple" },
  { label: "Apricot", value: "apricot" }
]

В этом случае логика отображения и вставки может быть изменена через item и replace.

Функция-источник

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

list: function () {
  return ["Alpha", "Beta", "Gamma"];
}

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

Асинхронная функция

Поддерживается возврат Promise:

list: function (input) {
  return fetch("/api/suggest?q=" + input)
    .then(r => r.json());
}

Такой подход используется при серверной фильтрации и больших наборах данных.

minChars — минимальное количество символов

Параметр minChars задаёт порог активации автодополнения.

minChars: 2

Поведение:

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

Используется для снижения нагрузки и уменьшения «шума» в интерфейсе.

maxItems — ограничение количества отображаемых элементов

maxItems определяет максимальное число подсказок, показываемых в выпадающем списке.

maxItems: 5

Механизм работы:

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

autoFirst — автоматический выбор первого элемента

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

autoFirst: true

При включении:

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

sort — функция сортировки результатов

Параметр sort определяет порядок элементов после фильтрации.

Сигнатура:

sort: function (a, b, input) {
    return 0;
}

Где:

  • a, b — элементы списка;
  • input — текущее значение поля ввода.

Пример лексикографической сортировки:

sort: function (a, b) {
    return a.localeCompare(b);
}

Полное отключение сортировки:

sort: function () {
    return 0;
}

filter — логика отбора элементов

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

Сигнатура:

filter: function (text, input) {
    return true;
}
  • text — значение элемента;
  • input — текущий ввод.

Стандартное поведение — поиск подстроки без учёта регистра:

filter: function (text, input) {
    return text.toLowerCase().includes(input.toLowerCase());
}

Используется для реализации:

  • префиксного поиска;
  • fuzzy-поиска;
  • регулярных выражений;
  • языковых нормализаций.

item — формирование DOM-элемента подсказки

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

Сигнатура:

item: function (text, input) {
    return document.createElement("li");
}

Стандартный механизм создаёт элемент <li> с подсветкой совпадений.

Пример кастомизации:

item: function (text, input) {
    const li = document.createElement("li");
    li.textContent = text;
    li.className = "suggestion-item";
    return li;
}

Возможности:

  • добавление HTML-разметки;
  • внедрение иконок;
  • выделение частей строки;
  • привязка dataset-атрибутов.

replace — логика вставки выбранного значения

Параметр replace определяет, как выбранный элемент подставляется в input.

Сигнатура:

replace: function (text) {}

Простейший вариант:

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

Расширенные сценарии:

вставка объекта

replace: function (item) {
    this.input.value = item.label;
    this.input.dataset.value = item.value;
}

форматирование строки

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

Используется для:

  • автодобавления разделителей;
  • нормализации значений;
  • разделения display/value логики.

data — преобразование исходных данных

Параметр data отвечает за нормализацию элементов списка перед фильтрацией и отображением.

Сигнатура:

data: function (item, input) {
    return item;
}

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

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

Используется для:

  • работы с API-ответами;
  • унификации структуры данных;
  • разделения внутренних и отображаемых значений.

max — устаревший параметр ограничения

В ранних версиях использовался параметр max, который ограничивал количество элементов.

max: 10

В современных конфигурациях заменён на maxItems, однако встречается в устаревших кодовых базах.

container — кастомизация контейнера (в расширенных сборках)

В некоторых расширенных реализациях присутствует параметр container, определяющий родительский DOM-элемент для списка подсказок.

container: document.querySelector(".autocomplete-container")

Позволяет:

  • встроить список в произвольную структуру DOM;
  • управлять позиционированием через внешний контейнер;
  • интегрировать компонент в сложные UI-системы.

Управление взаимодействием параметров

Параметры Awesomplete не работают изолированно. Их взаимодействие формирует полный цикл обработки данных:

  1. list предоставляет исходные данные
  2. data нормализует структуру
  3. filter отбирает подходящие элементы
  4. sort упорядочивает результат
  5. maxItems ограничивает выдачу
  6. item формирует DOM
  7. autoFirst задаёт поведение фокуса
  8. replace определяет итоговую вставку

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

Оглавление