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

Внутреннее состояние выбранных значений в Tom Select строится вокруг двух ключевых сущностей: массива выбранных значений (items) и синхронизации с исходным <select> элементом. Любое изменение состояния проходит через единый слой API-методов, которые обеспечивают согласованность UI, DOM и внутренних структур данных.

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

Получение текущих значений

getValue()

Метод возвращает текущее состояние выбора. Формат результата зависит от конфигурации:

  • при multiple: false возвращается одиночное значение (строка или число)
  • при multiple: true возвращается массив значений

Сигнатура:

const value = select.getValue();

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

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

В мультивыборе результат всегда нормализуется в массив, даже если выбран один элемент.

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

setValue(value, silent)

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

select.setValue(['a', 'b']);

или для одиночного режима:

select.setValue('a');

Параметр silent управляет генерацией событий:

  • false (по умолчанию) — вызывает цепочку событий change
  • true — подавляет события

Поведение метода

При вызове выполняются следующие шаги:

  1. Очистка текущего состояния
  2. Валидация входных значений относительно доступных опций
  3. Обновление внутреннего массива items
  4. Синхронизация DOM <select>
  5. Перерисовка UI

Если значение отсутствует среди доступных опций, оно игнорируется.

Добавление одного значения

addItem(value, silent)

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

select.addItem('new-value');

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

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

  • предотвращает дублирование значений
  • выполняет проверку существования опции
  • автоматически активирует её в UI
  • обновляет DOM <option selected>

Если значение уже присутствует в items, операция игнорируется.

Сценарии использования

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

Удаление значения

removeItem(value, silent)

Удаляет конкретное значение из набора выбранных элементов.

select.removeItem('value-to-remove');

Поведение

  1. Поиск значения в items
  2. Удаление из внутреннего массива
  3. Снятие selected у соответствующего <option>
  4. Обновление интерфейса
  5. Генерация событий (если не silent)

Если значение отсутствует, метод завершает работу без изменений состояния.

Полная очистка выбора

clear(silent)

Метод сбрасывает все выбранные значения.

select.clear();

Внутренние шаги

  • очистка массива items
  • сброс всех selected атрибутов
  • обновление UI
  • возврат компонента в исходное состояние

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

Синхронизация значений с опциями

refreshItems()

Метод пересобирает состояние выбранных элементов на основе текущего набора <option> элементов.

select.refreshItems();

Назначение

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

  • динамическом изменении <option> в DOM
  • внешнем обновлении списка опций
  • загрузке данных после инициализации

Логика работы

  • сканирование всех <option selected>
  • сопоставление с внутренним списком items
  • перезапись состояния при расхождениях

Метод обеспечивает согласованность при внешнем вмешательстве в DOM.

Внутреннее хранение и нормализация

Состояние выбора хранится в виде массива items. Даже при одиночном выборе используется унифицированная модель, где:

  • одиночное значение — частный случай массива длиной 1
  • мультивыбор — расширенная форма массива

Нормализация выполняется на уровне API, что позволяет избежать различий в обработке UI-логики.

Поведение при программных изменениях

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

  1. обновление items
  2. обновление <select>
  3. обновление визуального списка выбранных элементов
  4. синхронизация состояния поиска и фильтров

Любое изменение инициирует пересборку отображаемого состояния, включая:

  • теги выбранных элементов
  • состояние input-поля
  • активные подсказки

Silent-режим и контроль событий

Во всех ключевых методах присутствует параметр silent.

Поддерживаемые методы:

  • setValue(value, silent)
  • addItem(value, silent)
  • removeItem(value, silent)
  • clear(silent)

Поведение silent=true

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

Поведение silent=false

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

Работа с дубликатами и валидацией

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

  • существует ли опция в списке
  • не находится ли значение уже в items

При несоответствии:

  • значение игнорируется
  • состояние не изменяется
  • UI не обновляется

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

Особенности поведения в мультивыборе

В режиме multiple: true управление значениями приобретает дополнительные особенности:

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

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

Программная модификация состояния и цепочка обновлений

Любое изменение значения вызывает единый pipeline:

  • изменение модели данных
  • синхронизация DOM <select>
  • обновление UI-компонента
  • пересчет отображаемых элементов
  • обновление фильтрации поиска

Даже при минимальных изменениях (например, удаление одного элемента) выполняется полный цикл синхронизации, что гарантирует консистентность.

Связь методов управления значениями с состоянием поиска

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

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

Это особенно заметно при использовании addItem во время открытого dropdown: интерфейс моментально перестраивает видимые элементы.

Поведение при внешнем изменении DOM

Если <select> изменяется напрямую (без API), состояние может расходиться с внутренним items.

Для восстановления согласованности используется:

  • refreshItems()

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

Итоговая модель управления значениями

Система управления значениями в Tom Select построена вокруг нескольких базовых операций:

  • полная замена состояния (setValue)
  • точечное добавление (addItem)
  • точечное удаление (removeItem)
  • сброс (clear)
  • синхронизация с DOM (refreshItems)
  • чтение состояния (getValue)

Эти методы формируют единый API-слой, обеспечивающий предсказуемую работу компонента при любых сценариях изменения данных.

Оглавление