Группировка элементов

Группировка элементов в Tom Select позволяет логически структурировать список опций, объединяя их в категории и подкатегории. Это особенно важно при работе с большими наборами данных, где плоский список становится неудобным для восприятия и поиска. Механизм группировки встроен в архитектуру библиотеки и опирается на специальную структуру данных, где каждый элемент может быть привязан к группе через поле или вычисляемое свойство.

Tom Select поддерживает группировку через объектную модель данных. Каждый элемент списка должен содержать поле, определяющее принадлежность к группе. Чаще всего используется свойство optgroup или пользовательский ключ, передаваемый через конфигурацию optgroupField.

Базовый формат данных:

[
  {
    value: "1",
    text: "Apple",
    category: "Fruits"
  },
  {
    value: "2",
    text: "Carrot",
    category: "Vegetables"
  }
]

В этом случае поле category будет использовано для группировки элементов.

Настройка поля группировки

Ключевым параметром является optgroupField, который определяет, какое свойство объекта используется для формирования групп.

new TomSelect("#select", {
  valueField: "value",
  labelField: "text",
  optgroupField: "category",
  searchField: ["text"],
  options: [
    { value: "1", text: "Apple", category: "Fruits" },
    { value: "2", text: "Banana", category: "Fruits" },
    { value: "3", text: "Carrot", category: "Vegetables" }
  ]
});

После инициализации элементы автоматически распределяются по группам Fruits и Vegetables.

Автоматическое создание групп

Если группы не заданы явно, Tom Select создаёт их автоматически на основе значений поля optgroupField. Это означает, что разработчику не нужно заранее определять структуру групп, достаточно корректно указать данные.

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

Явное определение групп

Помимо автоматической генерации, возможно явное задание групп через параметр optgroups. Это полезно, когда требуется контролировать порядок отображения, добавлять подписи или управлять поведением групп.

new TomSelect("#select", {
  valueField: "id",
  labelField: "name",
  optgroupField: "type",
  optgroups: [
    { value: "fruits", label: "Fruits" },
    { value: "vegetables", label: "Vegetables" }
  ],
  options: [
    { id: "1", name: "Apple", type: "fruits" },
    { id: "2", name: "Carrot", type: "vegetables" }
  ]
});

В этом случае отображаемое имя группы берётся из label, а внутреннее сопоставление — из value.

Сортировка групп

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

new TomSelect("#select", {
  optgroupField: "category",
  optgroupOrder: ["Vegetables", "Fruits"]
});

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

Поведение при поиске

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

Поиск выполняется по полям, указанным в searchField, но структура групп остаётся неизменной. Это означает, что результат всегда сохраняет контекст категорий, что улучшает восприятие списка.

Группы в режиме remote data

При использовании удалённых источников данных (например, через load), группировка применяется после получения ответа. Сервер может возвращать уже сгруппированные данные или плоский список, который затем преобразуется клиентом.

Пример обработки:

new TomSelect("#select", {
  load: function(query, callback) {
    fetch("/api/items?q=" + encodeURIComponent(query))
      .then(res => res.json())
      .then(data => callback(data));
  },
  optgroupField: "category"
});

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

Пользовательский рендеринг групп

Tom Select позволяет переопределять шаблоны отображения групп через render.optgroup. Это даёт полный контроль над HTML-структурой заголовка группы.

new TomSelect("#select", {
  optgroupField: "category",
  render: {
    optgroup: function(data, escape) {
      return `<div class="optgroup-header">${escape(data.label)}</div>`;
    }
  }
});

Функция escape используется для предотвращения XSS и обязательна при выводе пользовательских данных.

Иерархическая группировка

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

{
  value: "1",
  text: "Apple",
  category: "Fruits / Citrus"
}

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

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

При большом количестве элементов группировка становится фактором производительности. Основная нагрузка возникает при:

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

Оптимизация достигается за счёт:

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

Управление пустыми группами

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

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

Комбинирование с множественным выбором

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

new TomSelect("#select", {
  optgroupField: "category",
  maxItems: 3
});

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

Динамическое изменение группировки

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

Типичный подход:

const control = new TomSelect("#select", {
  optgroupField: "category"
});

control.clearOptions();
control.addOptions(newData);
control.refreshOptions(false);

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

Поведение при отсутствии группировки

Если optgroupField не задан, все элементы отображаются в виде единого списка без категорий. Это базовый режим, используемый для небольших наборов данных, где структурирование не требуется.

Отсутствие группировки также снижает сложность DOM-структуры и повышает скорость отрисовки, особенно при больших объёмах данных.

Оглавление