Метод setSelected

setSelected — метод экземпляра Slim Select, предназначенный для программного управления выбранными значениями в выпадающих списках. Используется для установки одного или нескольких активных значений без взаимодействия пользователя с интерфейсом. Является частью API управления состоянием компонента и напрямую влияет на внутреннюю модель выбора и синхронизацию с оригинальным <select>.

Метод вызывается на экземпляре Slim Select:

instance.setSelected(value);

Параметры

  • value — строка, массив строк или значение, соответствующее value у <option>:

    • строка — для одиночного выбора
    • массив строк — для множественного выбора
    • null или пустой массив — для очистки выбора (в зависимости от конфигурации)

Возвращаемое значение отсутствует.

Назначение метода

Основная функция setSelected заключается в изменении текущего состояния выбранных элементов без необходимости триггера пользовательских событий интерфейса. Метод работает с внутренним состоянием Slim Select и приводит к обновлению:

  • отображения выбранных значений
  • состояния оригинального <select>
  • связанных событий (change, select, deselect в зависимости от конфигурации)

Поведение при одиночном выборе

При работе с одиночным <select> метод принимает строковое значение, соответствующее value одной из <option>.

const select = new SlimSelect({
  select: '#single'
});

select.setSelected('2');

В результате:

  • выбранная опция со значением "2" становится активной
  • предыдущий выбор снимается автоматически
  • интерфейс обновляется синхронно

Если передано значение, отсутствующее в списке, поведение зависит от версии Slim Select: обычно игнорируется или приводит к очистке выбора при строгой конфигурации.

Поведение при множественном выборе

При включённой опции multiple: true метод принимает массив значений:

const select = new SlimSelect({
  select: '#multi'
});

select.setSelected(['1', '3', '5']);

Результат:

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

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

Форматы значений

Метод работает исключительно с value атрибутами <option>:

<select id="example">
  <option value="a">Alpha</option>
  <option value="b">Beta</option>
  <option value="c">Gamma</option>
</select>

Использование:

select.setSelected('b');

или

select.setSelected(['a', 'c']);

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

Программная модель обновления

При вызове setSelected происходит несколько внутренних этапов:

  1. Поиск соответствующих элементов в data-структуре Slim Select
  2. Обновление массива выбранных значений
  3. Синхронизация состояния с DOM <select>
  4. Перерисовка UI-компонента
  5. Триггер событий изменения состояния

Эти операции выполняются атомарно, что исключает промежуточные неконсистентные состояния интерфейса.

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

Slim Select поддерживает двустороннюю синхронизацию. После вызова метода:

  • у <option> устанавливается selected = true/false
  • у <select> обновляется состояние value или набор selectedOptions
  • внешние обработчики могут реагировать на стандартное событие change

Пример наблюдаемого поведения:

document.querySelector('#multi').addEventListener('change', (e) => {
  console.log(e.target.selectedOptions);
});

select.setSelected(['2', '4']);

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

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

В зависимости от версии и настроек Slim Select, вызов setSelected может инициировать:

  • change — стандартное DOM-событие
  • select — событие выбора элемента
  • deselect — событие снятия выбора

Последовательность событий зависит от того, изменяется ли состояние частично или полностью.

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

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

Перезапись состояния

Метод всегда заменяет текущее состояние, а не модифицирует его:

select.setSelected(['1']);
select.setSelected(['2']);
// итоговое состояние: только '2'

Работа с несуществующими значениями

Если значение отсутствует в списке <option>:

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

Пустое значение

select.setSelected([]);

Результат:

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

Для одиночного селекта аналогично может использоваться null.

Взаимодействие с disabled состоянием

Если опция имеет атрибут disabled, поведение зависит от версии:

  • значение может быть проигнорировано
  • либо визуально не отображаться, даже если установлено программно
  • DOM может содержать selected=true, но UI не отразит это состояние

Отличие от других методов управления

setSelected vs setData

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

setSelected vs addItem/removeItem

  • setSelected выполняет массовую замену состояния
  • addItem добавляет одно значение к текущему набору
  • removeItem удаляет конкретное значение

setSelected vs set

В некоторых реализациях set может быть алиасом или низкоуровневым методом обновления состояния, тогда как setSelected — более специализированный интерфейс для выбора.

Асинхронные сценарии

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

select.setData([
  { text: 'One', value: '1' },
  { text: 'Two', value: '2' }
]);

select.setSelected(['2']);

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

Типичные сценарии применения

Инициализация состояния

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

select.setSelected('3');

Восстановление состояния

При повторном открытии формы или восстановлении из localStorage:

const saved = JSON.parse(localStorage.getItem('state'));
select.setSelected(saved.selected);

Синхронизация с сервером

После получения данных API:

fetch('/api/user')
  .then(res => res.json())
  .then(data => {
    select.setSelected(data.roles);
  });

Программное переключение состояния

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

if (mode === 'admin') {
  select.setSelected(['1', '2', '3']);
}

Поведение при повторных вызовах

Многократный вызов setSelected приводит к полной перерасчётной перерисовке состояния:

select.setSelected(['1']);
select.setSelected(['1', '2']);
select.setSelected(['1', '2', '3']);

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

Влияние на производительность

При больших списках (сотни и тысячи опций):

  • метод может вызывать заметную перерисовку UI
  • частые вызовы подряд создают лишние обновления DOM
  • оптимальным считается группирование значений в один вызов
select.setSelected(largeArray); // предпочтительно
Оглавление