Формат данных

В библиотеке Tom Select структура данных играет ключевую роль, поскольку именно она определяет, как элементы отображаются, фильтруются, выбираются и сериализуются. В отличие от простых HTML-элементов <select>, где данные ограничены атрибутами <option>, Tom Select работает с унифицированной моделью объектов, позволяющей гибко управлять источниками данных, отображением и взаимодействием.

Базовая структура элемента

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

  • value — уникальный идентификатор элемента
  • text — отображаемый текст
  • disabled — флаг недоступности (опционально)
  • optgroup — принадлежность к группе (опционально)
  • $order — внутренний порядок сортировки (используется при необходимости сохранения стабильного порядка)

Пример базового объекта:

{
  value: "1",
  text: "Москва"
}

Эта структура является основной единицей, с которой работает Tom Select при добавлении, удалении и отображении элементов.

Использование строкового формата

В некоторых случаях Tom Select допускает упрощённый формат данных — массив строк. В этом случае строки автоматически преобразуются в объекты с одинаковыми value и text.

Пример:

["HTML", "CSS", "JavaScript"]

После нормализации:

[
  { value: "HTML", text: "HTML" },
  { value: "CSS", text: "CSS" },
  { value: "JavaScript", text: "JavaScript" }
]

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

Формат данных в опциях инициализации

При инициализации Tom Select данные могут передаваться через параметр options. Это основной способ задания набора элементов.

new TomSelect("#select", {
  options: [
    { value: "ru", text: "Русский" },
    { value: "en", text: "English" }
  ]
});

Каждый объект в массиве интерпретируется как отдельный вариант выбора.

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

Связь с HTML <option>

При инициализации на основе существующего <select> элементы автоматически преобразуются в внутренний формат Tom Select.

HTML:

<select id="select">
  <option value="1">Первый</option>
  <option value="2">Второй</option>
</select>

Внутреннее представление:

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

Если присутствует атрибут disabled, он также переносится в объект:

<option value="3" disabled>Третий</option>
{
  value: "3",
  text: "Третий",
  disabled: true
}

Поддержка группировки данных

Tom Select поддерживает группировку элементов через поле optgroup. Это позволяет структурировать список иерархически.

{
  value: "paris",
  text: "Париж",
  optgroup: "france"
}

Группы могут быть определены отдельно:

optgroups: [
  { value: "france", label: "Франция" },
  { value: "germany", label: "Германия" }
]

Каждый элемент связывается с группой через совпадение optgroup.

Пользовательские поля и расширение модели

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

{
  value: "ru",
  text: "Русский",
  code: "RU",
  region: "Eastern Europe",
  population: 144000000
}

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

  • шаблонах отображения (render)
  • кастомной фильтрации (score)
  • обработчиках событий

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

Формат данных при асинхронной загрузке

При загрузке данных через load функция ожидает массив объектов в том же формате, что и options.

new TomSelect("#select", {
  load: function(query, callback) {
    fetch(`/api/cities?q=${query}`)
      .then(res => res.json())
      .then(data => {
        callback(data);
      });
  }
});

Ответ API должен соответствовать структуре:

[
  { value: "msk", text: "Москва" },
  { value: "spb", text: "Санкт-Петербург" }
]

Несоответствие формата приводит к некорректному отображению или отсутствию элементов.

Нормализация данных внутри Tom Select

Перед использованием данные проходят процесс нормализации. Он включает:

  • приведение строк к объектам {value, text}
  • проверку уникальности value
  • добавление служебных полей
  • приведение типов к строковому виду (в большинстве случаев)

Пример нормализации:

Вход:

[{ value: 1, text: "Один" }]

После обработки:

[{ value: "1", text: "Один" }]

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

Сериализация выбранных значений

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

Метод getValue() возвращает:

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

Пример:

select.getValue(); // "ru"

или

select.getValue(); // ["ru", "en"]

При этом возвращаются именно value, а не полный объект.

Обратное получение объектов

Для получения полных объектов используется метод getItem или доступ к внутренней коллекции элементов.

Внутреннее представление сохраняет исходные данные:

select.options["ru"]

Результат:

{
  value: "ru",
  text: "Русский",
  code: "RU"
}

Таким образом, value выступает ключом для быстрого доступа к данным.

Валидация структуры данных

Tom Select ожидает строгого соответствия минимальной структуре. Основные требования:

  • наличие value
  • наличие text (или его аналога через label в некоторых конфигурациях)
  • уникальность ключей
  • отсутствие undefined и null в критических полях

Нарушение этих условий приводит к:

  • дублированию элементов
  • невозможности выбора
  • некорректной фильтрации

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

При динамическом обновлении списка через addOption, removeOption или clearOptions используется тот же формат объектов.

select.addOption({
  value: "de",
  text: "Deutsch"
});

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

Внутренние идентификаторы и стабильность данных

Для обеспечения стабильного поведения Tom Select использует value как основной идентификатор. Это означает:

  • изменение text не влияет на идентичность элемента
  • изменение value фактически создаёт новый элемент
  • порядок элементов может контролироваться через $order
{
  value: "1",
  text: "Москва",
  $order: 10
}

Поле $order используется внутренней системой сортировки и не должно изменяться без необходимости, так как влияет на стабильность отображения.

Совместимость форматов данных

Tom Select допускает несколько входных форматов:

  • массив строк
  • массив объектов {value, text}
  • HTML <select> элементы
  • асинхронные JSON-ответы

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

Итоговая модель данных

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

Оглавление