Awesomplete построена вокруг простой, но гибкой модели данных: источник автодополнения чаще всего представляет собой массив строк. Именно этот формат используется в большинстве базовых сценариев и позволяет быстро интегрировать библиотеку без дополнительной подготовки данных.
В простейшем случае Awesomplete принимает массив строк, каждая из которых становится отдельным вариантом автодополнения. Библиотека выполняет поиск по этому массиву и отображает совпадения в выпадающем списке.
const input = document.querySelector("#city");
new Awesomplete(input, {
list: ["Almaty", "Astana", "Karaganda", "Shymkent", "Aktobe"]
});Каждая строка в массиве воспринимается как самостоятельный элемент. При вводе текста выполняется сопоставление по подстроке, что позволяет реализовать базовое автодополнение без дополнительных настроек.
Алгоритм поиска в массиве строк основан на сравнении введённого значения с каждым элементом списка. По умолчанию используется нечувствительное к регистру сравнение.
Основные особенности:
Пример поведения:
list: ["JavaScript", "TypeScript", "Java", "Python"]Ввод script вернёт:
Ввод java вернёт:
Использование массива строк накладывает ряд ограничений, связанных с простотой структуры данных:
При увеличении сложности интерфейса эти ограничения становятся критичными, однако в простых сценариях они не мешают работе.
Awesomplete автоматически приводит строки к единому регистру для сравнения. Это поведение можно учитывать при формировании массива.
list: ["React", "redux", "REDUX Toolkit", "Vue"]При вводе red будут найдены:
При этом отображаемый текст остаётся неизменным, так как библиотека не модифицирует исходные строки.
Массив строк может быть изменён во время выполнения. Awesomplete поддерживает обновление списка без пересоздания экземпляра.
const awesomplete = new Awesomplete(input, {
list: ["Apple", "Banana", "Orange"]
});
awesomplete.list = ["Apple", "Apricot", "Avocado"];После обновления новые значения начинают использоваться при следующем вводе. Это позволяет реализовать динамические сценарии, например, загрузку данных с сервера.
Массив строк часто используется совместно с обработкой событий ввода. Это позволяет формировать список на основе текущего состояния приложения.
const fruits = ["Apple", "Banana", "Blueberry", "Blackberry"];
const awesomplete = new Awesomplete(input, {
list: fruits
});
input.addEventListener("input", () => {
console.log("Текущее значение:", input.value);
});Хотя сам список остаётся статичным, его можно пересобирать в зависимости от условий приложения.
Перед передачей в Awesomplete массив может быть предварительно отфильтрован. Это позволяет контролировать, какие элементы попадут в автодополнение.
const allCities = ["Almaty", "Astana", "Aktau", "Atyrau", "Karaganda"];
const filtered = allCities.filter(city => city.startsWith("A"));
new Awesomplete(input, {
list: filtered
});В этом случае в список попадут только элементы, начинающиеся на определённую букву или соответствующие заданному условию.
Массив строк может содержать повторяющиеся значения. Awesomplete не выполняет автоматическую дедупликацию, поэтому одинаковые элементы будут отображаться в списке.
list: ["JavaScript", "JavaScript", "TypeScript"]Повторения могут использоваться намеренно, например для увеличения веса определённых вариантов в пользовательском интерфейсе, однако чаще требуется предварительная очистка массива.
Порядок отображения результатов полностью зависит от исходного массива, если не применяется дополнительная логика. Сортировка может быть выполнена до передачи данных в Awesomplete.
const cities = ["Shymkent", "Almaty", "Astana"];
cities.sort();
new Awesomplete(input, {
list: cities
});В этом случае элементы будут отображаться в алфавитном порядке.
Хотя массив строк чаще используется как статическая структура, он легко адаптируется для асинхронной загрузки. После получения данных массив заменяется целиком или обновляется частично.
fetch("/api/cities")
.then(res => res.json())
.then(data => {
awesomplete.list = data;
});Данные должны быть приведены к массиву строк до передачи в библиотеку, иначе поведение может быть непредсказуемым.
При увеличении количества элементов возрастает нагрузка на механизм поиска. Awesomplete не использует сложные структуры индексации, поэтому производительность напрямую зависит от размера массива.
Практические особенности:
Каждая строка из массива отображается без изменений. HTML-экранирование выполняется автоматически, что предотвращает вставку разметки.
list: ["<script>alert(1)</script>", "Normal text"]В интерфейсе первая строка будет показана как текст, без выполнения кода.
Даже при использовании простого массива строк можно влиять на поведение библиотеки через дополнительные параметры:
minChars — минимальное количество символов для
активации;maxItems — максимальное число отображаемых
вариантов;autoFirst — автоматический выбор первого элемента.new Awesomplete(input, {
list: ["Alpha", "Beta", "Gamma", "Delta"],
minChars: 1,
maxItems: 5,
autoFirst: true
});Эти параметры не изменяют структуру массива, но влияют на способ его использования.
В реальных приложениях массив строк часто формируется из других источников данных. Перед использованием он приводится к нужному формату.
const users = [
{ name: "Alex" },
{ name: "Boris" },
{ name: "Charlie" }
];
const list = users.map(u => u.name);
new Awesomplete(input, { list });Такая трансформация позволяет интегрировать Awesomplete в системы с объектной моделью данных без изменения самой библиотеки.