Обзор параметров конфигурации

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

Базовая форма инициализации:

const instance = new Choices('#select', {
  searchEnabled: true,
  removeItemButton: true,
  shouldSort: false
});

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

Инициализационные параметры

searchEnabled

Управляет наличием строки поиска внутри компонента.

  • true — активирует фильтрацию элементов
  • false — отключает поиск полностью
searchEnabled: true

При отключении поиска список работает как статический контрол выбора.

shouldSort

Определяет необходимость сортировки элементов внутри выпадающего списка.

shouldSort: false

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

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

searchChoices

Регулирует включение поиска по доступным опциям.

searchChoices: true

При значении false поиск может быть ограничен только уже выбранными элементами.

silent

Отключает генерацию событий при инициализации.

silent: true

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

Параметры данных

items

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

items: ['JavaScript', 'TypeScript']

Поддерживает:

  • строки
  • объекты с value и label
  • смешанные структуры при кастомной нормализации

choices

Основной источник данных для списка.

choices: [
  { value: 'js', label: 'JavaScript' },
  { value: 'ts', label: 'TypeScript' }
]

Поддерживаются дополнительные поля:

  • selected
  • disabled
  • customProperties

duplicateItemsAllowed

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

duplicateItemsAllowed: false

При false предотвращается повторное добавление уже выбранных элементов.

fuseOptions

Настройки алгоритма поиска (используется Fuse-подобная логика).

fuseOptions: {
  threshold: 0.3,
  distance: 100
}

Влияет на:

  • строгость совпадений
  • чувствительность к опечаткам
  • ранжирование результатов

Поведение ввода и фильтрации

searchFloor

Минимальное количество символов для активации поиска.

searchFloor: 2

При значении 0 поиск выполняется сразу при фокусе.

searchResultLimit

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

searchResultLimit: 10

Используется для оптимизации больших списков.

position

Определяет позиционирование выпадающего списка относительно поля.

position: 'auto'

Возможные значения:

  • auto
  • top
  • bottom

resetScrollPosition

Сбрасывает прокрутку списка при каждом новом поисковом запросе.

resetScrollPosition: true

Поведенческие настройки интерфейса

removeItemButton

Добавляет кнопку удаления выбранного элемента.

removeItemButton: true

Особенности:

  • влияет только на UI
  • не изменяет логику хранения данных
  • может быть переопределено через шаблоны

duplicateItemsAllowed

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

editItems

Позволяет редактировать уже выбранные элементы.

editItems: true

При включении:

  • двойной клик открывает редактирование
  • значение становится редактируемым текстом

maxItemCount

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

maxItemCount: 5

После достижения лимита:

  • новые элементы блокируются
  • может быть активирован callback события переполнения

maxItemText

Текст, отображаемый при достижении лимита.

maxItemText: (maxItemCount) =>
  `Максимум ${maxItemCount} элементов`

Конфигурация поиска

placeholder

Текст-заполнитель в поле ввода.

placeholder: true

Дополнительные варианты:

  • placeholderValue
  • searchPlaceholderValue

placeholderValue

Статический текст плейсхолдера.

placeholderValue: 'Выбор значения'

searchPlaceholderValue

Плейсхолдер внутри строки поиска.

searchPlaceholderValue: 'Поиск...'

Конфигурация выбора и поведения элементов

allowHTML

Разрешает HTML в отображаемых значениях.

allowHTML: false

При true возможно внедрение HTML-разметки в label.

addItems

Позволяет добавлять новые элементы вручную.

addItems: true

Если отключено:

  • ввод игнорируется
  • доступны только предопределённые значения

addItemFilter

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

addItemFilter: (value) => value.length > 1

Настройки дублирования и уникальности

uniqueItemText

Сообщение при попытке добавить дубликат.

uniqueItemText: 'Значение уже добавлено'

Используется в связке с duplicateItemsAllowed.

Конфигурация событий

callbackOnInit

Вызывается после полной инициализации компонента.

callbackOnInit: () => {
  console.log('initialized');
}

callbackOnCreateTemplates

Позволяет модифицировать шаблоны при создании.

callbackOnCreateTemplates: (template) => template

Используется для:

  • кастомизации DOM
  • внедрения новых элементов UI
  • изменения структуры рендера

Темплейты и визуализация

classNames

Позволяет переопределять CSS-классы.

classNames: {
  containerOuter: 'choices',
  containerInner: 'choices__inner',
  item: 'choices__item'
}

Важные особенности:

  • не ломает базовую структуру
  • позволяет интеграцию с UI-фреймворками
  • может использоваться для BEM/utility классов

itemSelectText

Текст, отображаемый при наведении на элемент списка.

itemSelectText: 'Выбрать'

Конфигурация доступности

renderSelectedChoices

Управляет отображением выбранных элементов в списке.

renderSelectedChoices: 'auto'

Варианты:

  • true
  • false
  • auto

loadingText

Текст состояния загрузки.

loadingText: 'Загрузка...'

noResultsText

Сообщение при отсутствии результатов поиска.

noResultsText: 'Ничего не найдено'

Поведенческие ограничения

searchResultLimit

Ограничение числа результатов поиска.

searchResultLimit: 15

Влияет на производительность при больших наборах данных.

sorter

Кастомная функция сортировки.

sorter: (a, b) => a.label.localeCompare(b.label)

Позволяет:

  • реализовать локализованную сортировку
  • учитывать внешние параметры
  • отключить стандартную сортировку через shouldSort

Расширенные параметры

addItemText

Функция формирования текста добавления нового элемента.

addItemText: (value) => `Добавить "${value}"`

valueComparer

Кастомная логика сравнения значений.

valueComparer: (a, b) => a === b

Используется при:

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

Итоговая структура конфигурационного объекта

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

{
  searchEnabled: true,
  shouldSort: false,
  choices: [],
  items: [],
  maxItemCount: 10,
  removeItemButton: true,
  placeholderValue: 'Select...',
  noResultsText: 'No results'
}

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

Оглавление