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

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

Ключевые компоненты состояния:

  • items — текущие выбранные значения (внутренний массив моделей)
  • options — набор доступных элементов для выбора
  • input (textbox) — состояние текстового ввода
  • control state — визуальное представление выбранных элементов
  • dropdown state — состояние раскрытия списка и активных элементов

Tom Select поддерживает как декларативное обновление через методы API, так и императивное управление внутренним состоянием с возможностью подавления побочных эффектов.

Управление выбранными значениями (items)

setValue

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

select.setValue("value1");
select.setValue(["value1", "value2"]);

Поддерживается как одиночное значение, так и массив. В случае мультиселекта происходит полная перезапись массива items.

Дополнительный параметр silent отключает триггеры событий и визуальные обновления:

select.setValue(["a", "b"], true);

addItem

Метод добавляет новый элемент в состояние без полной замены существующего набора.

select.addItem("value1");

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

  • значение добавляется только если оно существует в options
  • предотвращается дублирование (в зависимости от конфигурации)
  • вызывает обновление UI и событийную цепочку

С подавлением событий:

select.addItem("value1", true);

removeItem

Удаление конкретного значения из текущего состояния:

select.removeItem("value1");

При удалении происходит:

  • исключение элемента из items
  • обновление визуального списка тегов
  • пересчёт состояния input и dropdown

Silent-режим:

select.removeItem("value1", true);

clear

Полная очистка выбранных значений:

select.clear();

Эквивалент удаления всех items с последующей синхронизацией интерфейса.

Silent-режим:

select.clear(true);

Управление текстовым вводом

setTextboxValue

Метод напрямую управляет содержимым input-поля внутри компонента.

select.setTextboxValue("search text");

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

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

Управление списком опций (options)

addOption

Добавление новой опции в доступный список значений:

select.addOption({
  value: "new_value",
  text: "New Label"
});

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

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

updateOption

Обновление существующей опции по ключу:

select.updateOption("value1", {
  text: "Updated Label"
});

Поведение:

  • заменяет данные опции
  • пересоздаёт отображение при необходимости
  • сохраняет связь с выбранными items, если они уже активны

clearOptions

Полная очистка списка доступных опций:

select.clearOptions();

После вызова:

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

refreshOptions

Метод пересчитывает и перерисовывает список опций на основе текущего состояния фильтра.

select.refreshOptions();

Применяется при:

  • изменении фильтров
  • обновлении данных извне
  • изменении input value

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

sync

Метод sync приводит DOM-состояние компонента к внутреннему состоянию модели.

select.sync();

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

  • внешнее изменение DOM <select>
  • ручное вмешательство в структуру options
  • восстановление после batch-операций

Процесс синхронизации включает:

  • обновление items
  • пересборку options
  • синхронизацию input
  • корректировку UI состояния

Управление состоянием UI и поведения

focus и blur

Хотя эти методы напрямую не меняют data-state, они влияют на интерактивное состояние компонента:

select.focus();
select.blur();
  • focus активирует input и открывает взаимодействие с dropdown
  • blur завершает редактирование и закрывает список

Внутренние механизмы обновления состояния

Каждое изменение состояния в Tom Select проходит через цепочку:

  1. Обновление модели (items / options)
  2. Пересчёт индексов поиска
  3. Обновление фильтрации dropdown
  4. Перерисовка DOM
  5. Генерация событий (change, item_add, item_remove и др.)

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

select.addItem("value1", true);
select.addOption({ value: "v2", text: "V2" });
select.refreshOptions();
select.sync();

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

Управление состоянием через комбинированные операции

В реальных сценариях состояние часто изменяется группами операций:

select.clear(true);

select.addOption({ value: "1", text: "One" });
select.addOption({ value: "2", text: "Two" });

select.setValue(["1", "2"], true);

select.refreshOptions();

Такой подход позволяет:

  • минимизировать перерисовки
  • избежать лишних событий
  • контролировать момент синхронизации UI

Работа с частично согласованным состоянием

Tom Select допускает временные несоответствия между items и options, которые устраняются при следующих операциях:

  • sync() — восстановление полной согласованности
  • refreshOptions() — пересчёт видимых элементов
  • setValue() — принудительная нормализация выбранных значений

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

Событийная реакция на изменение состояния

Изменения состояния сопровождаются цепочкой событий:

  • добавление элемента → item_add
  • удаление элемента → item_remove
  • изменение значения → change
  • обновление options → option_add, option_remove
  • синхронизация → initialize, dropdown_open, dropdown_close

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

Оглавление