Программное управление

Awesomplete предоставляет набор методов, позволяющих полностью управлять поведением автодополнения без участия пользовательских событий. Программное управление строится вокруг экземпляра компонента, который сохраняется в переменной и используется для вызова внутренних API.

Экземпляр создаётся поверх DOM-элемента текстового поля и хранится в переменной:

const input = document.querySelector("#city");
const awesomplete = new Awesomplete(input, {
    minChars: 1,
    autoFirst: true
});

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

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

Принудительное открытие и закрытие списка

Управление видимостью выпадающего списка реализуется через методы open() и close().

awesomplete.open();
awesomplete.close();

Открытие списка

Метод open():

  • создаёт и отображает контейнер подсказок
  • применяет текущий набор данных (list)
  • учитывает фильтр, если значение в input уже введено

При отсутствии подходящих данных список может оставаться пустым, но DOM-структура всё равно создаётся.

Закрытие списка

Метод close():

  • скрывает список
  • сбрасывает активный индекс выбора
  • сохраняет введённое значение в поле input

Закрытие не очищает данные и не сбрасывает фильтры.

Навигация по элементам списка

Навигационные методы управляют активной строкой подсказок.

next()

awesomplete.next();

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

previous()

awesomplete.previous();

Перемещает активный выбор вверх по списку.

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

goto(index)

awesomplete.goto(2);

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

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

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

Программный выбор значения

select()

Метод select() имитирует выбор текущего активного элемента:

awesomplete.select();

При вызове:

  • значение выбранного элемента подставляется в input
  • список закрывается
  • генерируется событие выбора (если подключены события библиотеки)

Этот метод эквивалентен нажатию Enter по активной строке.

Пересчёт и обновление списка

evaluate()

awesomplete.evaluate();

Метод выполняет повторную обработку текущего значения input и обновляет список подсказок.

Внутренне происходит:

  • чтение текущего значения поля
  • применение фильтра (filter)
  • формирование массива результатов (data)
  • перерисовка списка

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

  • программном изменении значения input
  • обновлении источника данных
  • изменении конфигурации minChars, list, filter

Программное изменение значения input

Хотя прямой метод установки значения не всегда документирован как основной API, изменение состояния обычно сопровождается вызовом evaluate():

input.value = "Mos";
awesomplete.evaluate();

Такой подход гарантирует синхронизацию UI и внутреннего состояния.

Управление списком данных

Замена источника данных

Список подсказок может быть изменён динамически:

awesomplete.list = ["London", "Los Angeles", "Lisbon"];
awesomplete.evaluate();

После обновления списка требуется повторная оценка, иначе интерфейс останется в старом состоянии.

Фильтрация на уровне конфигурации

Фильтрация контролируется функцией filter:

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

Программное изменение фильтра позволяет:

  • реализовать fuzzy-поиск
  • отключить фильтрацию полностью
  • заменить алгоритм сопоставления

Управление жизненным циклом компонента

destroy()

awesomplete.destroy();

Метод полностью удаляет:

  • DOM-элементы списка
  • обработчики событий
  • внутренние ссылки на input

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

Состояние активности и внутренние флаги

Программное управление часто опирается на внутренние состояния:

  • opened — открыт ли список
  • selectedIndex — текущий индекс выбора
  • input.value — источник фильтрации

Изменение этих состояний напрямую не рекомендуется, но используется в расширениях логики поверх библиотеки.

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

Программные методы часто комбинируются с DOM-событиями:

input.addEventListener("focus", () => awesomplete.open());
input.addEventListener("blur", () => awesomplete.close());

Также возможно принудительное обновление при изменении данных:

fetch("/cities")
    .then(r => r.json())
    .then(data => {
        awesomplete.list = data;
        awesomplete.evaluate();
    });

Комбинирование навигации и выбора

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

awesomplete.open();
awesomplete.goto(0);
awesomplete.select();

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

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

В системах автозаполнения часто требуется внешний контроль:

function setCity(city) {
    input.value = city;
    awesomplete.evaluate();
    awesomplete.open();
}

Этот паттерн используется при:

  • автозаполнении по геолокации
  • выборе значений из сторонних компонентов
  • синхронизации с API

Ограничение программного управления

Несмотря на широкий API, ряд аспектов остаётся внутренним:

  • рендеринг DOM не предназначен для кастомной модификации
  • события выбора не всегда вызываются при прямом изменении value
  • внутренние свойства могут изменяться между версиями

Поэтому управление строится через публичные методы, а не через прямое вмешательство в состояние объекта.

Оглавление