Список всех событий

Choices.js реализует событийно-ориентированную архитектуру, в которой любые изменения состояния компонента (выбор элементов, ввод текста, открытие выпадающего списка, фильтрация) транслируются через набор стандартных событий экземпляра. Эти события позволяют синхронизировать интерфейс, интегрировать сторонние модули и строить реактивную логику поверх компонента.

События выбора элементов

addItem

Срабатывает при добавлении нового элемента в выбранное значение (selected items).

Передаваемые данные включают:

  • value — значение добавленного элемента
  • item — объект модели элемента
  • id — внутренний идентификатор

Используется при:

  • выборе элемента из списка
  • добавлении тега (в режиме multiple)
  • вставке значения через API

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

removeItem

Срабатывает при удалении элемента из выбранных значений.

Передаваемые данные:

  • value — значение удалённого элемента
  • item — объект удалённой модели
  • id — идентификатор элемента

Событие отражает любые способы удаления:

  • клик по кресту у тега
  • удаление через клавиатуру (Backspace/Delete)
  • программное удаление через API

choice

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

Передаваемые данные:

  • choice — объект выбранного элемента
  • item — нормализованная модель

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

События изменения состояния

change

Срабатывает при любом изменении итогового значения компонента.

Передаваемое значение:

  • value — текущее состояние выбранных значений (строка или массив, в зависимости от режима)

Характеристика:

  • агрегирующее событие
  • вызывается после addItem и removeItem
  • отражает финальное состояние, а не промежуточные шаги

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

События поиска

Срабатывает при вводе текста в поле поиска внутри Choices.js.

Передаваемые данные:

  • value — строка поиска
  • result — массив отфильтрованных элементов

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

  • вызывается при каждом изменении input
  • отражает результат локальной или серверной фильтрации (если включён remote search)
  • используется для кастомизации логики поиска или интеграции с API

События работы с выпадающим списком

showDropdown

Срабатывает при открытии выпадающего списка.

Не содержит сложных payload-данных, фиксирует только факт изменения состояния интерфейса.

Типичные причины срабатывания:

  • фокусировка на поле ввода
  • клик по инпуту
  • программное открытие dropdown через API

hideDropdown

Срабатывает при закрытии выпадающего списка.

Срабатывает при:

  • потере фокуса
  • выборе элемента (в зависимости от конфигурации)
  • нажатии Escape
  • программном закрытии через API

highlightItem

Срабатывает при изменении активного (подсвеченного) элемента в списке.

Передаваемые данные:

  • item — текущий выделенный элемент

Используется для:

  • навигации клавиатурой (ArrowUp / ArrowDown)
  • визуального контроля состояния фокуса внутри dropdown

Событийная цепочка взаимодействий

Внутри Choices.js события образуют последовательные цепочки, отражающие пользовательские сценарии:

Выбор элемента из списка

  1. search (если ввод был активен)
  2. showDropdown (если список был закрыт)
  3. highlightItem (при навигации)
  4. choice (факт выбора)
  5. addItem (добавление в состояние)
  6. change (обновление итогового значения)

Удаление элемента

  1. removeItem
  2. change

Открытие списка

  1. showDropdown
  2. highlightItem (если есть активный элемент)

Закрытие списка

  1. hideDropdown

Особенности работы событийной системы

Синхронная модель исполнения

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

Независимость событий

События не блокируют друг друга и не влияют напрямую на внутреннее состояние компонента. Например, обработка search не прерывает highlightItem, а change вызывается независимо от источника изменения данных.

Повторяемость

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

  • search — на каждый ввод символа
  • highlightItem — при каждой навигации по списку

Разделение логики состояния и UI

Choices.js строго разделяет:

  • события UI (showDropdown, hideDropdown, highlightItem)
  • события данных (addItem, removeItem, change)
  • события ввода (search, choice)

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

Взаимосвязь событий и внутреннего состояния

Каждое событие отражает конкретную фазу изменения внутреннего состояния:

  • массив выбранных значений обновляется через addItem и removeItem
  • строковое представление синхронизируется через change
  • визуальное состояние dropdown управляется через showDropdown и hideDropdown
  • контекст навигации фиксируется через highlightItem
  • поисковый фильтр активируется через search

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

Оглавление