Полный список событий

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

События в Tom Select делятся на несколько категорий: жизненный цикл компонента, работа с выбранными элементами, управление списком опций, ввод и поиск, а также взаимодействие с интерфейсом.

Подписка и механизм обработки событий

Для работы с событиями используется стандартный API экземпляра:

  • on(event, handler) — регистрация обработчика
  • off(event, handler) — удаление обработчика
  • trigger(event, ...) — вызов события (внутренний механизм библиотеки и расширений)

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

Типовая структура:

const ts = new TomSelect('#select');

ts.on('change', value => {
    console.log(value);
});

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

События жизненного цикла компонента

initialize

Срабатывает после полной инициализации экземпляра, когда DOM-структуры построены, данные загружены и компонент готов к взаимодействию.

Характерные особенности:

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

focus

Активируется при получении фокуса полем ввода.

Событие отражает переход компонента в активное состояние:

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

blur

Срабатывает при потере фокуса.

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

  • фиксирует завершение взаимодействия
  • часто используется для валидации и синхронизации состояния

Генерируется при открытии выпадающего списка.

Событие отражает момент:

  • раскрытия списка опций
  • расчёта позиции dropdown
  • подготовки DOM-элементов для отображения

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

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

destroy

Вызывается при уничтожении экземпляра компонента.

Событие сопровождается:

  • удалением DOM-элементов
  • освобождением обработчиков
  • очисткой внутренних структур

События работы с выбранными значениями

change

Ключевое событие изменения значения.

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

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

Передаёт актуальное состояние выбранных значений.

item_add

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

Аргументы обычно включают:

  • значение элемента
  • DOM-узел (если доступен)

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

item_remove

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

Отражает момент:

  • удаления тега
  • обновления внутреннего состояния

item_select

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

Используется в сценариях:

  • навигации по списку
  • клавиатурного выбора
  • кликов по опциям

item_deselect

Событие снятия выбора с ранее активного элемента.

Отражает переход элемента из состояния “выбран” в “не выбран”.

clear

Срабатывает при полном очищении выбранных значений.

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

  • сбросе формы
  • программной очистке состояния

События управления списком опций

option_add

Генерируется при добавлении новой опции в список.

Характерно для динамических сценариев:

  • загрузка данных из API
  • ручное добавление значений

option_remove

Срабатывает при удалении опции из списка доступных значений.

Отражает синхронизацию с источником данных.

optgroup_add

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

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

optgroup_remove

Событие удаления группы опций вместе с её содержимым.

События ввода, поиска и загрузки данных

type

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

Фиксирует:

  • текущее значение input
  • пользовательскую активность

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

Генерируется в процессе выполнения поиска по опциям.

Отражает момент обработки строки поиска и применения фильтрации.

load

Срабатывает при успешной загрузке данных из внешнего источника.

Используется в асинхронных режимах работы:

  • AJAX-загрузка опций
  • динамическое пополнение списка

load_error

Генерируется при ошибке загрузки данных.

Содержит информацию о сбое:

  • статус ответа
  • текст ошибки
  • контекст запроса

События создания новых элементов

create

Активируется при попытке создания нового значения, отсутствующего в списке опций.

Отражает сценарий:

  • ввод нового тега
  • добавление пользовательского значения

create_item

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

События взаимодействия с интерфейсом

Помимо базового жизненного цикла, эти события часто используются для:

  • управления позиционированием интерфейса
  • синхронизации с внешними компонентами
  • контроля состояния overlay-слоёв

focus / blur

Дополнительно применяются для:

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

Внутренние и расширенные события

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

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

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

Поведенческие цепочки событий

Многие действия в Tom Select формируют последовательности:

  • ввод текста → type → search → обновление списка
  • добавление значения → item_add → change
  • создание элемента → create → option_add → item_add → change
  • очистка → clear → change

Такая структура обеспечивает предсказуемость состояния и позволяет точно отслеживать каждое изменение внутри компонента.

Контекст выполнения событий

Каждое событие выполняется в контексте экземпляра компонента. Это означает доступ к:

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

Контекст обеспечивает возможность модификации поведения без необходимости внешнего хранения состояния.

Приоритет и переопределение событий

Система допускает множественные обработчики на одно событие. Порядок выполнения определяется порядком регистрации.

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

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

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

Все события Tom Select тесно связаны с внутренним состоянием:

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

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

Оглавление