Описание всех методов

Экземпляр Choices после инициализации получает набор методов, которые управляют состоянием списка, выбранными значениями, поиском, выпадающим меню и внутренним хранилищем. Эти методы образуют основной программный API библиотеки и позволяют полностью контролировать поведение селектора без прямого вмешательства в DOM.

Инициализация создаёт объект:

const instance = new Choices(element, options);

После этого доступен набор методов instance.

Управление значениями

setValue(items)

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

instance.setValue(['apple', 'orange']);

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

  • массив значений
  • одиночное значение (в зависимости от конфигурации)
  • объекты с расширенной структурой

Используется для синхронизации с внешними данными, например API или формами восстановления состояния.

getValue(valueOnly)

Возвращает текущие выбранные значения.

const values = instance.getValue();

Параметр valueOnly:

  • true — возвращает только значения
  • false — возвращает объекты с метаданными (label, selected, disabled и т.д.)

setChoiceByValue(value)

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

instance.setChoiceByValue('banana');

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

removeActiveItems(excludedItem)

Удаляет выбранные элементы из активного списка.

instance.removeActiveItems();

Параметр excludedItem позволяет сохранить конкретный элемент при очистке.

removeItem(item)

Удаляет конкретный выбранный элемент.

instance.removeItem(itemObject);

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

removeItemByValue(value)

Более удобная форма удаления по значению:

instance.removeItemByValue('apple');

addItem(value, label, choiceId, groupId, customProperties, placeholder)

Добавляет новый выбранный элемент программно.

instance.addItem('pear', 'Pear');

Расширенная сигнатура позволяет:

  • задавать ID выбора
  • привязывать к группе
  • передавать пользовательские свойства
  • указывать placeholder-элементы

Управление списком опций

setChoices(choices, value, label, replaceChoices)

Полностью или частично задаёт список доступных опций.

instance.setChoices([
  { value: 'ru', label: 'Russia' },
  { value: 'kz', label: 'Kazakhstan' }
], 'value', 'label', true);

Параметры:

  • choices — массив данных
  • value — поле значения
  • label — поле отображаемого текста
  • replaceChoices — заменять ли текущие опции

clearChoices()

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

instance.clearChoices();

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

clearStore()

Полностью очищает внутреннее хранилище библиотеки:

  • выбранные значения
  • доступные опции
  • состояние поиска
instance.clearStore();

Применяется при полной переинициализации компонента.

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

clearInput()

Очищает поле ввода поиска.

instance.clearInput();

Часто используется после выбора элемента или сброса формы.

highlightItem(item, runEvent)

Программно устанавливает фокус на элемент списка.

instance.highlightItem(item);

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

removeHighlightedItems()

Снимает выделение с активного элемента списка.

instance.removeHighlightedItems();

Управление состоянием интерфейса

showDropdown()

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

instance.showDropdown();

Используется для программного контроля UI.

hideDropdown()

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

instance.hideDropdown();

toggleDropdown()

Переключает состояние dropdown между открытым и закрытым.

instance.toggleDropdown();

Управление доступностью

disable()

Полностью отключает компонент:

  • блокируется ввод
  • отключается выбор
  • скрывается интерактивность
instance.disable();

enable()

Возвращает компонент в активное состояние.

instance.enable();

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

destroy()

Полностью уничтожает экземпляр Choices:

  • удаляет обработчики событий
  • восстанавливает исходный <select>
  • очищает DOM-обёртки
instance.destroy();

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

Внутренние и служебные методы поведения

init (внутренний метод)

Метод инициализации вызывается автоматически при создании экземпляра. Отвечает за:

  • построение структуры DOM
  • загрузку начальных значений
  • привязку событий

Прямое использование не предусмотрено.

Синхронизация состояния

Методы библиотеки тесно связаны между собой: изменение выбранных значений через setValue, addItem или setChoiceByValue автоматически приводит к обновлению:

  • отображения тегов
  • состояния списка
  • событий изменения (change, addItem, removeItem)

Любое программное вмешательство в состояние компонента проходит через единый слой синхронизации, обеспечивающий согласованность UI и данных.

Поведение методов при кастомных конфигурациях

При включённых режимах:

  • removeItemButton
  • searchEnabled
  • shouldSort
  • duplicateItemsAllowed

поведение методов может изменяться:

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

Методы остаются единым API, но их результат зависит от конфигурации экземпляра.

Оглавление