Загрузка статических данных

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

Базовая структура данных

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

  • value — уникальный идентификатор значения
  • text — отображаемый текст

Пример базового набора:

const options = [
  { value: "ru", text: "Русский" },
  { value: "en", text: "Английский" },
  { value: "de", text: "Немецкий" }
];

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

Инициализация с static options

Статическая загрузка реализуется через параметр options при создании экземпляра Tom Select:

new TomSelect("#select-language", {
  options: [
    { value: "ru", text: "Русский" },
    { value: "en", text: "Английский" },
    { value: "de", text: "Немецкий" }
  ]
});

В данном случае исходный <select> может быть пустым, поскольку весь список формируется из конфигурации JavaScript.

Использование существующего <select>

Если необходимо сохранить семантику HTML-разметки, статические данные могут быть переданы через <option> элементы. Tom Select автоматически считывает их при инициализации:

<select id="select-language">
  <option value="ru">Русский</option>
  <option value="en">Английский</option>
  <option value="de">Немецкий</option>
</select>
new TomSelect("#select-language");

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

Поддержка дополнительных полей

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

const options = [
  {
    value: "ru",
    text: "Русский",
    region: "EU",
    active: true
  },
  {
    value: "en",
    text: "Английский",
    region: "Global",
    active: true
  }
];

Такие данные не отображаются автоматически, но доступны в шаблонах и событиях.

Управление отображением через labelField и valueField

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

new TomSelect("#select-language", {
  options: [
    { code: "ru", name: "Русский" },
    { code: "en", name: "Английский" }
  ],
  valueField: "code",
  labelField: "name"
});

Здесь:

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

Группировка статических данных

Для структурированных списков используется поле optgroup. Оно позволяет разделять элементы на логические категории.

new TomSelect("#select-language", {
  optgroups: [
    { value: "europe", label: "Европа" },
    { value: "asia", label: "Азия" }
  ],
  options: [
    { value: "ru", text: "Русский", optgroup: "europe" },
    { value: "de", text: "Немецкий", optgroup: "europe" },
    { value: "jp", text: "Японский", optgroup: "asia" }
  ],
  optgroupField: "optgroup"
});

Такое разделение улучшает восприятие длинных списков и упрощает навигацию.

Поведение при дублировании значений

При статической загрузке Tom Select опирается на уникальность поля value. Если в массиве присутствуют дубликаты, поведение становится непредсказуемым: могут быть перезаписаны элементы или нарушена логика выбора. Поэтому необходимо обеспечивать уникальность идентификаторов на уровне данных.

Предварительно выбранные значения

Статические данные позволяют легко задать начальное состояние компонента. Для этого используется свойство items:

new TomSelect("#select-language", {
  options: [
    { value: "ru", text: "Русский" },
    { value: "en", text: "Английский" }
  ],
  items: ["en"]
});

В результате элемент с value: "en" будет выбран сразу после инициализации.

Если используется HTML <select>, начальное состояние определяется атрибутом selected:

<option value="en" selected>Английский</option>

Обновление статических данных после инициализации

Хотя данные считаются статическими, Tom Select допускает их замену в рантайме через API:

const select = new TomSelect("#select-language");

select.clearOptions();

select.addOption({ value: "fr", text: "Французский" });
select.addOption({ value: "es", text: "Испанский" });

select.refreshOptions(false);

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

Фильтрация статического набора

Встроенный механизм поиска работает поверх массива options. Фильтрация осуществляется по полю labelField, что позволяет мгновенно находить совпадения без запросов к серверу.

Поведение поиска можно изменить через параметр score:

new TomSelect("#select-language", {
  options: [
    { value: "ru", text: "Русский" },
    { value: "en", text: "Английский" }
  ],
  score: function(search) {
    return function(item) {
      return item.text.toLowerCase().includes(search.toLowerCase()) ? 1 : 0;
    };
  }
});

Оптимизация больших статических массивов

При работе с большим количеством элементов (сотни или тысячи записей) важно учитывать производительность. Основные ограничения связаны не с хранением данных, а с рендерингом DOM-элементов.

Ключевые подходы:

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

Tom Select выполняет фильтрацию на клиенте, поэтому сложность поиска линейно зависит от размера массива.

Кастомный рендеринг статических данных

Каждая опция может быть визуально переопределена через шаблоны render. Это особенно полезно при использовании расширенных объектов:

new TomSelect("#select-language", {
  options: [
    { value: "ru", text: "Русский", flag: "??" },
    { value: "en", text: "Английский", flag: "??" }
  ],
  render: {
    option: function(data) {
      return `<div>${data.flag} ${data.text}</div>`;
    },
    item: function(data) {
      return `<div>${data.flag} ${data.text}</div>`;
    }
  }
});

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

Особенности сериализации данных

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

Типовые ошибки при работе со статическими данными

Часто встречаются следующие проблемы:

  • использование неуникальных value
  • несоответствие labelField фактической структуре объекта
  • попытка изменить исходный массив вместо API
  • смешивание HTML <option> и JavaScript options без понимания приоритета

Приоритет всегда отдаётся JavaScript-конфигурации, если она указана явно.

Поведение при пустом наборе данных

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

Оглавление