Добавление опций конфигурации

Конфигурация экземпляра Tom Select формируется в момент инициализации и передаётся вторым аргументом конструктора. Именно этот объект определяет поведение компонента: источники данных, правила отображения, поиск, создание новых значений и взаимодействие с DOM.

const select = new TomSelect('#select', {
  maxItems: 5,
  create: true,
  placeholder: 'Выбор значения'
});

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

Приоритеты конфигурации и порядок применения

Tom Select формирует итоговую конфигурацию через последовательное объединение нескольких уровней:

  1. Значения по умолчанию библиотеки
  2. Глобальные настройки, если заданы через расширение прототипа
  3. Конфигурация конкретного экземпляра
  4. Параметры, переданные плагинами

Конфликты разрешаются по принципу переопределения: более специфичный уровень перекрывает общий.

TomSelect.define('custom_defaults', {
  maxItems: 3
});

new TomSelect('#select', {
  maxItems: 10
});

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

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

Ограничение количества выбранных элементов

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

new TomSelect('#select', {
  maxItems: 1
});

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

Создание новых элементов

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

new TomSelect('#select', {
  create: true
});

Допускается использование функции, возвращающей объект новой опции:

new TomSelect('#select', {
  create: (input) => ({
    value: input.toLowerCase(),
    text: input
  })
});

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

Поля данных: value, label и поиск

Конфигурация структуры данных определяется тремя ключевыми параметрами:

  • valueField — поле, используемое как уникальный идентификатор
  • labelField — поле отображаемого текста
  • searchField — поля, участвующие в поиске
new TomSelect('#select', {
  valueField: 'id',
  labelField: 'title',
  searchField: ['title', 'description']
});

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

Настройка источников данных

Статический список опций

Передача массива объектов через параметр options позволяет полностью контролировать содержимое списка без обращения к DOM.

new TomSelect('#select', {
  options: [
    { id: 1, title: 'JavaScript' },
    { id: 2, title: 'TypeScript' }
  ]
});

Асинхронная загрузка данных

Параметр load определяет функцию получения данных при вводе текста.

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

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

Контроль условий загрузки

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

new TomSelect('#select', {
  shouldLoad: (query) => query.length > 2
});

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

Параметры отображения и интерфейса

Placeholder и начальное состояние

new TomSelect('#select', {
  placeholder: 'Поиск элемента'
});

Placeholder отображается до выбора первого значения и при пустом состоянии поля.

Максимальное количество отображаемых опций

new TomSelect('#select', {
  maxOptions: 50
});

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

Открытие и закрытие списка

new TomSelect('#select', {
  openOnFocus: true,
  closeAfterSelect: true
});
  • openOnFocus — автоматическое раскрытие при фокусе
  • closeAfterSelect — закрытие после выбора элемента

Настройка поиска

Поле сортировки результатов

new TomSelect('#select', {
  sortField: {
    field: 'text',
    direction: 'asc'
  }
});

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

Кастомизация алгоритма оценки

new TomSelect('#select', {
  score: function(search) {
    return function(item) {
      return item.text.toLowerCase().indexOf(search.toLowerCase()) !== -1 ? 1 : 0;
    };
  }
});

Функция score позволяет полностью переопределить механику релевантности результатов.

Управление значениями и состоянием

Предустановленные значения

new TomSelect('#select', {
  items: ['js', 'ts']
});

Список items задаёт начальное состояние выбранных элементов.

Сохранение состояния

new TomSelect('#select', {
  persist: false
});

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

Разрешение дубликатов

new TomSelect('#select', {
  create: true,
  persist: false,
  duplicates: false
});

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

Рендеринг и визуальная кастомизация

Шаблоны отображения

new TomSelect('#select', {
  render: {
    option: function(data, escape) {
      return `<div>${escape(data.title)}</div>`;
    },
    item: function(data, escape) {
      return `<div>${escape(data.title)}</div>`;
    }
  }
});

Объект render управляет HTML-структурой элементов списка и выбранных значений.

Индивидуальные классы элементов

new TomSelect('#select', {
  itemClass: 'ts-item',
  controlInput: '<input>'
});

Настройка классов позволяет интегрировать компонент в существующие UI-системы.

Плагины и расширение конфигурации

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

new TomSelect('#select', {
  plugins: ['remove_button', 'dropdown_input']
});

Каждый плагин способен добавлять собственные параметры:

TomSelect.define('example_plugin', function() {
  return {
    options: {
      customOption: true
    }
  };
});

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

Динамическое изменение конфигурации

Некоторые параметры могут быть изменены после инициализации через API экземпляра.

select.settings.maxItems = 10;
select.refreshOptions(false);

Однако изменение конфигурации на лету не всегда приводит к автоматическому пересчёту внутренних структур, поэтому часто требуется вызов методов обновления состояния.

Контекстная зависимость конфигурации

Конфигурация может зависеть от данных DOM-элемента, на котором инициализируется компонент. Атрибуты data-* могут использоваться как источник начальных значений, что позволяет формировать декларативные настройки.

<select id="select" data-placeholder="Выбор языка"></select>
new TomSelect('#select');

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

Механизм расширения базовых настроек

Для массового изменения поведения всех экземпляров используется модификация прототипа:

TomSelect.define('global_defaults', {
  maxOptions: 100
});

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

Влияние конфигурации на жизненный цикл компонента

Параметры конфигурации напрямую влияют на этапы инициализации:

  • загрузка данных инициируется load
  • построение интерфейса зависит от render
  • привязка событий определяется внутренними флагами поведения
  • начальное состояние формируется из items

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

Оглавление