Первичная конфигурация

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

Конфигурация формируется в момент создания экземпляра компонента и передаётся либо через конструктор, либо через HTML-атрибуты data-*. В JavaScript-инициализации используется объект параметров:

  • список данных (list)
  • ограничения ввода (minChars)
  • максимальное количество результатов (maxItems)
  • правила сортировки и фильтрации
  • поведение автозаполнения
  • форматирование элементов

Каждый параметр влияет на отдельный этап жизненного цикла автодополнения: от реакции на ввод до генерации выпадающего меню.

Источник данных list

Основой работы автодополнения является параметр list, определяющий набор вариантов.

Поддерживаются структуры:

  • массив строк
  • массив объектов
  • функция-генератор

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

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

При использовании объектов возможна привязка дополнительных данных:

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

Функциональный вариант позволяет динамическую подгрузку:

list: function() {
  return fetch("/data").then(r => r.json());
}

На этапе первичной конфигурации важно учитывать, что структура данных определяет поведение фильтрации и отображения.

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

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

new Awesomplete(input, {
  minChars: 2
});

Значение определяет минимальную длину строки ввода, при которой начинается поиск совпадений.

Поведение:

  • 0 — список отображается сразу
  • 1 — активация после первого символа
  • n > 1 — задержка до достижения длины строки

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

Ограничение количества элементов maxItems

Параметр управляет числом отображаемых результатов.

new Awesomplete(input, {
  maxItems: 5
});

Механизм ограничивает количество DOM-элементов в выпадающем списке, снижая визуальную перегрузку и ускоряя рендеринг.

Особенности:

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

Автовыбор первого элемента autoFirst

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

new Awesomplete(input, {
  autoFirst: true
});

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

  • первый элемент списка становится активным
  • возможна быстрая вставка без навигации
  • изменяется логика обработки клавиши Enter

При отключении выбор всегда требует явного действия.

Фильтрация filter

Функция filter определяет, какие элементы списка считаются подходящими.

Сигнатура:

filter: function(text, input) { }

Пример переопределения:

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

По умолчанию используется поиск по началу строки, но кастомизация позволяет реализовать:

  • поиск по подстроке
  • нечёткое сравнение
  • языковую нормализацию

Сортировка sort

Параметр sort задаёт порядок вывода результатов.

sort: function(a, b, input) {
  return a.length - b.length;
}

Стандартное поведение:

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

Переопределение позволяет реализовать:

  • сортировку по популярности
  • приоритет частоты использования
  • семантическое ранжирование

Формирование элементов item

Функция item отвечает за создание DOM-элементов списка.

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

Через этот механизм контролируется:

  • структура HTML элемента
  • наличие дополнительных атрибутов
  • визуальное оформление

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

Подстановка значения replace

Функция replace определяет, каким образом выбранный элемент вставляется в input.

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

Стандартное поведение — полная замена значения поля ввода.

Возможные сценарии:

  • вставка части строки
  • форматирование (например, добавление ID)
  • преобразование данных перед вставкой

Нормализация данных data

Функция data используется для извлечения значения из сложных структур.

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

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

  • отображаемое значение
  • фактическое значение

Интеграция через HTML-атрибуты

Первичная конфигурация может задаваться без JavaScript через data-*:

<input class="awesomplete"
       data-list="Apple, Banana, Cherry"
       data-minchars="1"
       data-maxitems="10" />

Особенности:

  • строки интерпретируются как списки
  • числовые значения приводятся автоматически
  • логические параметры принимают true/false

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

Порядок применения конфигурации

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

  1. считывание data-* атрибутов
  2. применение объекта конфигурации JavaScript
  3. установка значений по умолчанию
  4. инициализация событий ввода
  5. построение внутренней структуры списка

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

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

Комбинация настроек формирует итоговое поведение:

  • minChars влияет на момент активации
  • filter определяет состав результатов
  • sort изменяет порядок
  • maxItems ограничивает отображение
  • item и replace формируют UI и поведение выбора

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

Поведение по умолчанию

Без явной настройки используется базовая конфигурация:

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

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

Оглавление