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

Библиотека Tom Select предоставляет гибкий набор методов для работы с опциями, позволяя динамически изменять содержимое выпадающего списка, управлять состоянием выбранных элементов и синхронизировать данные с внешними источниками. Архитектура опций построена вокруг внутренней коллекции объектов, где каждая опция представляет собой структурированную запись с ключевыми полями: value, text, disabled, а также пользовательскими атрибутами.

addOption

Метод addOption() используется для добавления новой опции в текущий экземпляр. Он принимает объект, содержащий данные опции, и добавляет его во внутренний набор без автоматического выбора.

Сигнатура:

tomSelect.addOption(data)

Пример структуры опции:

{
  value: "1",
  text: "Первый элемент"
}

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

Ключевое поведение:

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

addOptions

Метод addOptions() предназначен для пакетного добавления нескольких опций. Это более эффективный способ по сравнению с последовательным вызовом addOption().

Сигнатура:

tomSelect.addOptions(arrayOfOptions)

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

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

  • оптимизированная вставка снижает количество перерисовок;
  • применяется при первичной загрузке данных;
  • сохраняет производительность при больших наборах (1000+ элементов).

updateOption

Метод updateOption() изменяет существующую опцию по её значению. Используется для синхронизации данных, пришедших из внешнего источника.

Сигнатура:

tomSelect.updateOption(value, data)

Если опция с указанным value отсутствует, обновление не выполняется.

Пример:

tomSelect.updateOption("1", {
  text: "Обновлённый текст"
})

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

  • обновляет только указанные поля;
  • сохраняет неизменённые свойства;
  • не влияет на выбранное состояние.

removeOption

Метод removeOption() удаляет опцию из внутреннего списка и из DOM-структуры, если она отображена.

Сигнатура:

tomSelect.removeOption(value)

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

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

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

clearOptions

Метод clearOptions() полностью очищает список доступных опций, не затрагивая выбранные значения.

Сигнатура:

tomSelect.clearOptions()

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

Ключевые моменты:

  • удаляет все элементы внутреннего кэша опций;
  • не сбрасывает выбранные значения автоматически;
  • требует последующего вызова addOptions() для восстановления списка.

clearOption

Метод clearOption() удаляет опцию и одновременно снимает её выбор, если она была активна.

Сигнатура:

tomSelect.clearOption(value)

В отличие от removeOption(), здесь дополнительно учитывается состояние выбора, что делает метод более строгим.

getOption

Метод getOption() возвращает DOM-элемент, связанный с указанной опцией.

Сигнатура:

tomSelect.getOption(value)

Возвращаемое значение — HTML-элемент списка, если опция существует, иначе undefined.

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

  • прямого доступа к DOM;
  • кастомной модификации отображения;
  • интеграции с внешними UI-библиотеками.

getOptions

Метод getOptions() возвращает полный набор доступных опций в виде объекта.

Сигнатура:

tomSelect.getOptions()

Результат представляет собой словарь, где ключ — это value, а значение — объект опции.

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

{
  "1": { value: "1", text: "Первый" },
  "2": { value: "2", text: "Второй" }
}

refreshOptions

Метод refreshOptions() инициирует перерасчёт и перерисовку списка опций без изменения данных.

Сигнатура:

tomSelect.refreshOptions()

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

Поведение:

  • пересчитывает видимые элементы;
  • применяет текущий фильтр поиска;
  • обновляет состояние выделения.

sync

Метод sync() синхронизирует внутреннее состояние Tom Select с исходным <select> элементом.

Сигнатура:

tomSelect.sync()

Основное назначение — обеспечение согласованности между DOM и внутренней моделью данных.

Сценарии применения:

  • внешнее изменение <option> в HTML;
  • динамическое обновление формы;
  • интеграция с серверным рендерингом.

setValue и setValueSilently

Метод setValue() изменяет выбранные значения, автоматически вызывая события обновления.

tomSelect.setValue(value)

Поведение:

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

Альтернативный метод setValueSilently() выполняет ту же операцию без генерации событий:

tomSelect.setValueSilently(value)

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

clear

Метод clear() полностью очищает выбранные значения.

tomSelect.clear()

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

  • не удаляет опции;
  • сбрасывает только selection state;
  • триггерит событие очистки.

addItem и removeItem

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

tomSelect.addItem(value)
tomSelect.removeItem(value)

addItem() выбирает опцию, если она существует, а removeItem() снимает выбор.

Поведение:

  • addItem() игнорирует несуществующие значения;
  • removeItem() безопасен при отсутствии элемента;
  • оба метода обновляют интерфейс синхронно.

disableOption и enableOption

Методы управления доступностью опций:

tomSelect.disableOption(value)
tomSelect.enableOption(value)

При отключении:

  • опция остаётся в списке;
  • становится недоступной для выбора;
  • визуально помечается как disabled.

При включении восстанавливается стандартное поведение.

toggleOption

Метод toggleOption() переключает состояние опции между активным и неактивным.

tomSelect.toggleOption(value)

Логика:

  • если опция отключена — включается;
  • если включена — отключается.

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

setTextboxValue (косвенное влияние на опции)

Хотя метод относится к поисковому полю, он влияет на отображение опций через фильтрацию:

tomSelect.setTextboxValue(text)

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

  • пересчёт видимых опций;
  • применение search-фильтра;
  • обновление списка.

Оптимизация работы с большими наборами

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

  • addOptions() вместо множественных addOption();
  • setValueSilently() вместо setValue() при массовых изменениях;
  • refreshOptions() только после завершения всех изменений.

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

Оглавление