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

new Choices(element, options) Создаёт новый экземпляр компонента. В качестве первого аргумента принимает DOM-элемент <select> или <input>, вторым аргументом — объект конфигурации. Именно через этот конструктор запускается вся логика библиотеки, включая построение внутреннего состояния, обработку DOM и регистрацию событий.

destroy() Полностью уничтожает экземпляр, возвращая исходный DOM-элемент к состоянию до инициализации. При вызове происходит:

  • удаление всех обработчиков событий;
  • восстановление нативного <select> (если он использовался);
  • очистка добавленных DOM-структур;
  • освобождение внутреннего состояния.

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

Методы управления списком вариантов

setChoices(choices, value, label, replaceChoices) Базовый метод для программного наполнения списка опций.

Параметры:

  • choices — массив объектов вариантов;
  • value — ключ, содержащий значение (например, id);
  • label — ключ отображаемого текста;
  • replaceChoices — булево значение, определяющее замену текущего списка.

Поведение:

  • при replaceChoices = true текущие варианты удаляются и заменяются новыми;
  • при false новые элементы добавляются к существующим.

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

clearChoices() Удаляет все доступные варианты выбора, не затрагивая выбранные элементы (если они уже активированы).

Основное применение:

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

clearStore() Полностью очищает внутреннее хранилище Choices.js, включая:

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

Фактически возвращает компонент в состояние «пустого контейнера» без разрушения экземпляра.

Методы управления выбранными значениями

setValueByChoice(value) Устанавливает выбранное значение на основе значения элемента из списка.

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

  • ищет совпадение в текущем наборе options;
  • активирует соответствующий item;
  • обновляет UI и внутреннее состояние.

setValue(value) Универсальный метод установки значения. Может принимать как одиночное значение, так и массив (в режиме multiple).

Поведение зависит от конфигурации:

  • single select — заменяет текущее значение;
  • multiple select — добавляет новое значение в список выбранных.

removeActiveItems(item) Удаляет активный (выбранный) элемент.

Используется в режимах multiple select для:

  • удаления тегов;
  • программного снятия выбора;
  • синхронизации состояния с внешними данными.

removeHighlightedItems() Снимает выделение с текущего активного (подсвеченного) элемента списка. Применяется при навигации с клавиатуры или сбросе фокуса внутри dropdown.

Методы управления интерфейсом

showDropdown() Открывает выпадающий список вариантов.

При вызове:

  • активируется контейнер dropdown;
  • применяется анимация появления (если включена);
  • устанавливается состояние фокуса.

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

hideDropdown() Закрывает выпадающий список.

Действия:

  • скрытие контейнера;
  • сброс состояния навигации;
  • фиксация текущего выбора.

Используется при потере фокуса или внешнем управлении UI.

highlightItem(item) Устанавливает визуальное выделение на конкретный элемент списка.

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

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

unhighlightItem() Снимает текущее выделение с элемента списка. Применяется при смене контекста поиска или закрытии dropdown.

Методы состояния компонента

enable() Активирует компонент после отключения.

Возвращает:

  • возможность взаимодействия с UI;
  • обработку событий;
  • ввод и выбор значений.

disable() Полностью отключает компонент.

Эффект:

  • блокировка взаимодействия;
  • отключение поиска;
  • визуальная индикация disabled-состояния.

При этом внутренние данные сохраняются.

Методы получения данных

getValue() Возвращает текущее значение компонента.

Формат результата зависит от режима:

  • single select — строка или объект;
  • multiple select — массив значений.

Дополнительно может возвращать полный объект выбора, если включены соответствующие опции конфигурации.

Вспомогательные методы поведения

setChoiceByValue(value) (в некоторых версиях API) Альтернативный метод установки значения по значению option. Используется для прямого выбора элемента без необходимости обращаться к DOM.

setHighlightedChoice(value) Устанавливает выделение на элемент, соответствующий переданному значению. Часто используется при синхронизации поиска и клавиатурной навигации.

Внутренние методы синхронизации состояния

Некоторые методы не всегда документируются как публичные, но встречаются в реальной работе с библиотекой и её расширениях.

refresh() Перестраивает DOM и синхронизирует внутреннее состояние с текущими данными.

Применяется при:

  • внешнем изменении данных;
  • ручной модификации состояния;
  • интеграции с динамическими фреймворками.

reset() Сбрасывает выбранные значения к начальному состоянию, заданному при инициализации.

Отличие от clearStore():

  • reset() восстанавливает исходные данные;
  • clearStore() полностью очищает состояние.

Методы поиска и фильтрации

setSearchTerm(value) Программно задаёт строку поиска внутри dropdown.

Поведение:

  • обновляет поле ввода;
  • пересчитывает список доступных вариантов;
  • активирует фильтрацию.

Используется при внешнем управлении поиском.

clearSearch() Очищает поисковый ввод и возвращает список к исходному состоянию.

Итоговая структура взаимодействия методов

Методы Choices.js образуют три логических слоя:

  • управление данными (setChoices, clearChoices, clearStore);
  • управление состоянием выбора (setValue, removeActiveItems, getValue);
  • управление интерфейсом (showDropdown, hideDropdown, highlightItem);
  • управление жизненным циклом (enable, disable, destroy).

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

Оглавление