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

Управление выбранными элементами в Choices.js строится вокруг набора методов, позволяющих программно синхронизировать состояние компонента с внешними данными. Основной механизм изменения выбора реализуется через методы установки значений.

setValue

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

Особенности поведения:

  • полностью перезаписывает текущий выбор
  • поддерживает одиночный и множественный режим
  • инициирует обновление UI и внутренних событий

При использовании в режиме множественного выбора массив заменяет весь список выбранных элементов, а не дополняет его.

setChoiceByValue

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

Основные свойства:

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

Применяется в случаях, когда выбор формируется на основе внешнего идентификатора, например ID из API.

setValueByChoice (устаревающие реализации)

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

Добавление и удаление выбранных элементов

addItem

Метод addItem добавляет новый элемент в список выбранных значений. В зависимости от конфигурации экземпляра компонент может:

  • добавить новый элемент в выбор
  • создать новый вариант в списке (если разрешено addItems: true)

Поведение определяется параметрами и текущим состоянием данных.

Ключевые особенности:

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

removeItem

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

Логика работы:

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

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

removeItemByValue

Метод removeItemByValue позволяет удалить выбранный элемент по его значению value, без необходимости передачи полного объекта.

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

  • работает напрямую с ключом value
  • оптимален для внешних идентификаторов
  • удобен при интеграции с API и серверными данными

Очистка выбранных данных

removeActiveItems

Метод removeActiveItems очищает активный выбор. Может работать как:

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

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

clearStore

Метод clearStore выполняет более радикальную очистку внутреннего состояния компонента:

  • удаляет выбранные элементы
  • очищает доступные варианты
  • сбрасывает кэшированные данные

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

clearChoices

Метод clearChoices очищает список доступных вариантов, не обязательно затрагивая текущий выбор.

Поведение:

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

Получение текущего состояния выбора

getValue

Метод getValue возвращает текущее состояние выбранных элементов. Может работать в двух режимах:

  • возврат массива объектов (полная структура)
  • возврат массива значений (упрощённый режим)

Управляется булевым параметром:

  • true — возвращаются только значения
  • false или отсутствие параметра — возвращаются объекты

Применяется для синхронизации состояния компонента с внешними системами.

Массовое управление выбором

setChoices

Метод setChoices позволяет полностью заменить набор доступных опций. Хотя он не относится напрямую к выбранным элементам, он влияет на состояние выбора при обновлении данных.

При использовании:

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

Типичный сценарий — динамическая загрузка списка из API с последующей синхронизацией выбранных значений.

Сброс и уничтожение состояния

reset

Метод reset возвращает компонент к начальному состоянию:

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

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

destroy

Метод destroy полностью удаляет экземпляр Choices.js:

  • удаляет все обработчики событий
  • очищает DOM-структуру компонента
  • освобождает память

После вызова восстановление возможно только через повторную инициализацию.

Синхронизация и внутренние эффекты

Каждый метод управления выбором влияет не только на визуальное состояние, но и на внутреннюю модель данных:

  • обновляется store выбранных значений
  • пересчитывается состояние доступных опций
  • триггерятся события изменения (change, addItem, removeItem)
  • синхронизируется скрытый <select> элемент

Особое значение имеет последовательность вызовов: при массовых изменениях предпочтительно использовать методы, заменяющие состояние целиком (setValue, setChoices), чтобы избежать множественных перерисовок.

Работа в режиме множественного выбора

При включённой опции множественного выбора (removeItem, addItem, setValue) методы управления работают с массивами значений. Важные особенности:

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

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

Оглавление