Полный список методов

setValue(value, silent)

Метод устанавливает текущее значение компонента. Принимает одиночное значение или массив значений (в режиме multiple).

value — строка, число или массив значений
silent — подавляет генерацию событий изменения состояния

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

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

getValue()

Возвращает текущее значение селекта. В зависимости от конфигурации может возвращать:

строку (single select)
массив значений (multiple select)

Метод используется как основной способ извлечения состояния компонента без обращения к DOM. Значения всегда соответствуют valueField, указанному в конфигурации.

addItem(value, silent)

Добавляет элемент в выбранные значения без полной перезаписи состояния.

value — значение, соответствующее одному из элементов списка
silent — подавляет события change

При вызове метод:

Проверяет наличие опции в списке
Добавляет её в выбранные элементы
Обновляет UI
При необходимости загружает данные асинхронно (если используется remote load)

В режиме multiple допускается множественное добавление без удаления существующих значений.

removeItem(value, silent)

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

value — значение для удаления
silent — подавление событий

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

удаление DOM-элемента выбранного тега
обновление внутреннего массива значений
перерасчёт состояния input

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

clear(silent)

Полностью очищает выбранные значения.

Метод выполняет:

сброс массива выбранных значений
удаление всех тегов из интерфейса
восстановление пустого состояния input

Используется как базовая операция сброса состояния компонента.

Методы работы с опциями

addOption(data)

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

data — объект с полями, соответствующими настройкам labelField и valueField

Если опция с таким значением уже существует, добавление не выполняется. Метод не инициирует перерисовку списка автоматически, требуется refreshOptions.

addOptions(array)

Добавляет массив опций за один вызов.

array — массив объектов опций

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

updateOption(value, data)

Обновляет существующую опцию.

value — идентификатор опции
data — новые данные объекта

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

removeOption(value)

Удаляет опцию из списка доступных значений.

value — значение опции

Если удаляемая опция находится в выбранных элементах, она также удаляется из текущего состояния. После выполнения требуется обновление интерфейса.

clearOptions()

Полностью очищает список доступных опций.

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

Методы поиска и фильтрации

refreshOptions(triggerDropdown)

Пересчитывает и перерисовывает список доступных опций на основе текущего запроса.

triggerDropdown — при значении true открывает выпадающий список после обновления

Метод применяет текущий фильтр поиска и заново формирует DOM-элементы списка. Используется после изменения данных или программного обновления состояния.

search(query)

Выполняет поиск по доступным опциям.

query — строка запроса

Метод возвращает результаты фильтрации, учитывая настройки:

searchField
sortField
score

При использовании remote-режима может инициировать асинхронную загрузку данных через load.

load(query, callback)

Асинхронная загрузка данных для заполнения списка опций.

query — поисковая строка
callback — функция обратного вызова с результатами

Метод предназначен для интеграции с API. При каждом вызове может выполняться HTTP-запрос. Результаты передаются в callback, после чего добавляются в список через addOptions.

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

open()

Открывает выпадающий список опций.

При вызове:

вычисляется позиция dropdown
формируется список видимых элементов
активируется режим навигации по клавиатуре

close()

Закрывает выпадающий список.

Сбрасывает состояние активного фокуса внутри dropdown и прекращает обработку навигационных событий.

focus()

Устанавливает фокус на input-элемент селекта.

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

blur()

Снимает фокус с компонента и переводит его в неактивное состояние.

disable()

Полностью отключает компонент.

Эффект:

блокировка ввода
отключение взаимодействия с dropdown
добавление визуального состояния disabled

enable()

Восстанавливает активное состояние компонента после disable.

destroy()

Полностью уничтожает экземпляр компонента.

Происходит:

удаление всех обработчиков событий
очистка DOM-структуры, созданной библиотекой
восстановление исходного select-элемента (при необходимости)

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

Методы синхронизации и состояния

sync()

Синхронизирует внутреннее состояние компонента с оригинальным <select> элементом.

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

refreshItems()

Перерисовывает список выбранных элементов без изменения данных.

Метод используется при изменении отображения (например, кастомизация шаблонов или CSS), когда данные остаются неизменными.

setTextboxValue(value)

Устанавливает текст в поле ввода поиска.

value — строка для отображения в input

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

setCaret(index)

Устанавливает позицию курсора внутри input-поля или списка выбранных элементов.

index — позиция курсора

Метод применяется для управления вводом в сложных сценариях редактирования тегов.

getCaret()

Возвращает текущую позицию курсора.

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

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

positionDropdown()

Пересчитывает и устанавливает позицию выпадающего списка относительно input-элемента.

Метод учитывает:

размер окна
прокрутку страницы
доступное пространство снизу и сверху

В случае нехватки места dropdown может открываться вверх.

Вспомогательные методы

registerPlugin(name, plugin)

Регистрирует расширение функциональности компонента.

name — идентификатор плагина
plugin — функция расширения

Метод позволяет модифицировать поведение без изменения ядра библиотеки.

clearCache()

Очищает внутренний кеш поиска и результатов загрузки.

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

getOption(value)

Возвращает объект опции по значению.

Позволяет получить доступ к внутренним данным элемента без обхода DOM-структуры.

getItem(value)

Возвращает DOM-элемент выбранного значения.

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

refreshState()

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

Метод объединяет синхронизацию значений, опций и интерфейса, устраняя рассогласование между слоями представления и модели данных.