Событие addItem

Событие addItem в Choices.js является ключевым механизмом реакции на добавление нового элемента в инстанс кастомного селектора. Оно возникает каждый раз, когда пользователь выбирает значение из списка или добавляет новый элемент (в случае режима тегов). Событие позволяет отслеживать момент изменения состояния выбора на уровне данных, а не только UI.

Момент срабатывания события

Событие addItem генерируется после того, как элемент:

  • выбран из выпадающего списка;
  • добавлен программно через API;
  • создан пользователем (если включён режим создания новых значений);
  • успешно прошёл все внутренние проверки Choices.js (валидация, дубликаты, ограничения по количеству).

Событие не вызывается при первичной инициализации списка, даже если значения устанавливаются через конфигурацию choices.setValue() до завершения инициализации.

Структура события

В стандартной реализации Choices.js событие addItem передаётся как нативное DOM-событие, привязанное к исходному элементу <select> или <input>.

Основные данные доступны через event.detail:

  • value — значение добавленного элемента;
  • label — отображаемый текст элемента;
  • id — внутренний идентификатор Choices.js;
  • choice — объект выбора, содержащий метаданные элемента;
  • groupValue — значение группы, если элемент добавлен из группированного списка.

Пример структуры:

{
  value: "javascript",
  label: "JavaScript",
  id: 3,
  choice: {
    value: "javascript",
    label: "JavaScript",
    selected: true,
    disabled: false
  }
}

Подключение обработчика

Обработчик события привязывается к исходному DOM-элементу, который был передан в Choices.js:

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

const choices = new Choices(element);

element.addEventListener('addItem', (event) => {
  const { value, label } = event.detail;
  console.log('Добавлен элемент:', value, label);
});

Важно учитывать, что обработчик работает именно с DOM-элементом, а не с экземпляром choices.

Поведение при множественном выборе

В режиме multiple: true событие addItem вызывается для каждого добавленного элемента отдельно. При массовом добавлении через API или автозаполнение последовательность событий сохраняется, что позволяет отслеживать порядок вставки.

Пример поведения:

choices.setValue([
  { value: 'html', label: 'HTML' },
  { value: 'css', label: 'CSS' }
]);

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

Добавление через пользовательский ввод

При включённой опции addItems: true и duplicateItemsAllowed: false событие addItem срабатывает только после успешного создания нового элемента. Если введённое значение не проходит проверку на дубликат, событие не генерируется.

Также при включённой опции createItems: true событие фиксирует создание новых значений, отличая их от выбора существующих элементов.

Отличие от change

Событие addItem часто путают с change, однако между ними существует принципиальная разница:

  • addItem фиксирует добавление конкретного элемента;
  • change фиксирует общее изменение состояния выбора.

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

Программное добавление значений

Choices.js генерирует addItem не только при пользовательском взаимодействии, но и при программных изменениях:

choices.setChoiceByValue('react');

или

choices.setValue([{ value: 'vue', label: 'Vue' }]);

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

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

Событие не вызывается в следующих случаях:

  • попытка добавить уже выбранный элемент при duplicateItemsAllowed: false;
  • добавление отключённого (disabled) элемента;
  • превышение лимита maxItemCount;
  • ошибки валидации пользовательского ввода.

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

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

addItem часто используется совместно с:

  • removeItem — для отслеживания полного жизненного цикла элемента;
  • search — для анализа пользовательского ввода перед добавлением;
  • choice — для реагирования на выбор из списка;
  • change — для финальной синхронизации состояния.

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

Обработка данных события

Практическая обработка addItem обычно включает:

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

Пример логики обработки:

element.addEventListener('addItem', (event) => {
  const item = event.detail;

  syncToServer({
    action: 'add',
    value: item.value
  });

  updateUIState(item);
});

Особенности поведения в режиме тегов

При использовании Choices.js как тегового компонента (removeItemButton: true, duplicateItemsAllowed: false) событие addItem становится основным источником данных о новых тегах. Каждый введённый и подтверждённый тег формирует отдельное событие, что позволяет строить системы автосохранения или динамической фильтрации.

Взаимодействие с группами

При работе с группированными списками (optgroup) событие addItem сохраняет информацию о принадлежности элемента к группе через groupValue. Это позволяет различать источники добавленных элементов при сложной структуре данных.

element.addEventListener('addItem', (event) => {
  const group = event.detail.groupValue;

  if (group) {
    handleGroupedItem(event.detail);
  }
});
Оглавление