Установка значения программно

Работа с программной установкой значений в Choices.js опирается на управление состоянием экземпляра компонента через его API. В отличие от стандартных HTML select-элементов, где изменение значения ограничено DOM-манипуляциями или присвоением value, библиотека Choices.js предоставляет набор методов, позволяющих изменять выбранные значения с учётом внутренней модели данных, синхронизации UI и событийной системы.

Каждый экземпляр Choices.js хранит данные в виде структурированных объектов опций. Внутри различаются:

  • список доступных опций (choices)
  • выбранные значения (selected)
  • внутренний индекс для быстрого поиска

Программная установка значения всегда проходит через синхронизацию этих структур, а не напрямую через DOM.

Основной метод установки значения

Центральным инструментом является метод:

setChoiceByValue(value)

Он применяется для установки одного значения или массива значений в зависимости от конфигурации элемента.

Установка одиночного значения

const element = document.querySelector('#select');
const choices = new Choices(element);

choices.setChoiceByValue('apple');

При выполнении происходит:

  1. Поиск опции с соответствующим value
  2. Обновление внутреннего состояния selected
  3. Перерисовка UI
  4. Генерация событий изменения состояния

Важно, что значение должно существовать в списке choices, иначе установка игнорируется.

Установка нескольких значений

Для мультиселекта метод принимает массив:

choices.setChoiceByValue(['apple', 'banana', 'orange']);

В этом случае библиотека:

  • очищает текущее состояние выбора
  • проверяет каждое значение на наличие в списке опций
  • добавляет валидные элементы в selected
  • синхронизирует интерфейс тегов (если включён режим multiple)

Особенность заключается в том, что порядок значений в массиве сохраняется в интерфейсе, что важно при работе с приоритетными списками.

Поведение при отсутствующих значениях

Если переданное значение не найдено среди доступных опций:

  • оно игнорируется
  • ошибок не выбрасывается
  • состояние выбора остаётся неизменным для этого элемента

Такой подход предотвращает разрушение состояния при динамическом изменении данных.

Программная очистка перед установкой

Во многих сценариях требуется явная очистка перед установкой нового набора значений. Choices.js предоставляет метод:

clearStore()

или более специализированный:

removeActiveItems()

Пример последовательности:

choices.removeActiveItems();
choices.setChoiceByValue(['one', 'two']);

Это гарантирует отсутствие остаточных выбранных значений.

Установка значений через addItem

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

addItem(item)

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

choices.addItem({
  value: 'new-value',
  label: 'New Value',
  selected: true
});

В отличие от setChoiceByValue, этот метод:

  • не требует предварительного наличия опции
  • может расширять список choices
  • используется при режиме addItems: true

Синхронизация с DOM-элементом

Каждое программное изменение значения приводит к синхронизации с исходным <select> элементом:

  • обновляется selectedIndex или selectedOptions
  • генерируется событие change
  • поддерживается корректная работа формовой отправки

Таким образом, Choices.js остаётся совместимой с нативным поведением HTML-форм.

Работа с disabled состояниями

При программной установке значений библиотека учитывает:

  • disabled опции
  • disabled инстанса
  • флаг shouldSort

Если значение соответствует disabled-элементу, оно не будет выбрано, даже при явном указании в setChoiceByValue.

Поведение в режиме поиска

При активированном поиске (search enabled):

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

Это предотвращает потерю выбранных значений при динамическом поиске.

Перезапись значения и реактивность

Повторный вызов setChoiceByValue полностью перезаписывает текущее состояние:

choices.setChoiceByValue('apple');
choices.setChoiceByValue('banana');

В результате выбранным останется только banana.

Каждое изменение сопровождается внутренними событиями:

  • addItem
  • removeItem
  • change

Это позволяет подключать внешнюю реактивную логику.

Работа с кастомными объектами

При использовании сложных данных структура значения может быть расширена:

choices.setChoiceByValue([
  { value: '1', label: 'One' },
  { value: '2', label: 'Two' }
]);

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

Особенности повторной инициализации

Если экземпляр Choices.js пересоздаётся:

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

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

При установке большого количества значений важно учитывать:

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

Пример оптимального подхода:

choices.setChoiceByValue(largeArray);

вместо:

largeArray.forEach(v => choices.setChoiceByValue(v));

Интеграция с динамическими источниками данных

При загрузке данных через API часто используется последовательность:

  1. загрузка options
  2. инициализация Choices
  3. установка значений
fetch('/api/options')
  .then(r => r.json())
  .then(data => {
    const choices = new Choices('#select', {
      choices: data
    });

    choices.setChoiceByValue(['preselected']);
  });

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

Ограничения программной установки

Существуют ключевые ограничения:

  • невозможность выбрать значение вне списка без addItem
  • игнорирование disabled элементов
  • зависимость от текущей конфигурации select (single/multiple)
  • отсутствие обхода валидации

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

Оглавление