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

Библиотека Choices.js оперирует строго структурированными данными, которые описывают элементы списка выбора. В отличие от нативного <select>, где структура задаётся через HTML-опции, здесь всё строится вокруг JavaScript-объектов и массивов, которые проходят нормализацию внутри библиотеки.

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

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

Каждый элемент в Choices.js представляет собой объект со следующей базовой структурой:

{
  value: 'uk',
  label: 'United Kingdom'
}

Основные поля:

value Уникальное значение, которое будет отправлено в форме или использовано в логике приложения.

label Отображаемый текст элемента в списке.

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

Полная структура объекта элемента

Помимо базовых свойств, Choices.js поддерживает расширенный набор параметров:

{
  value: 'us',
  label: 'United States',
  selected: false,
  disabled: false,
  placeholder: false,
  customProperties: {
    continent: 'North America',
    code: 'USA'
  }
}

Дополнительные поля:

selected Определяет, выбран ли элемент при инициализации.

disabled Блокирует возможность выбора элемента.

placeholder Помечает элемент как плейсхолдер, который не участвует в выборе.

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

Передача данных при инициализации

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

const choices = new Choices('#select', {
  choices: [
    { value: 'ru', label: 'Russia' },
    { value: 'kz', label: 'Kazakhstan' },
    { value: 'us', label: 'United States' }
  ]
});

В этом случае массив choices полностью заменяет необходимость использования <option> внутри HTML-элемента.

Смешанный формат: HTML + JavaScript данные

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

const choices = new Choices('#select');

choices.setChoices([
  { value: 'de', label: 'Germany' },
  { value: 'fr', label: 'France' }
], 'value', 'label', false);

Аргументы setChoices:

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

Группировка элементов (аналог optgroup)

Choices.js поддерживает группировку элементов через поле group:

[
  {
    label: 'Europe',
    id: 'eu',
    choices: [
      { value: 'de', label: 'Germany' },
      { value: 'fr', label: 'France' }
    ]
  },
  {
    label: 'Asia',
    id: 'asia',
    choices: [
      { value: 'kz', label: 'Kazakhstan' },
      { value: 'jp', label: 'Japan' }
    ]
  }
]

Особенности группового формата:

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

Нормализация входных данных

Choices.js автоматически приводит входные данные к внутреннему стандарту. Даже если данные поступают в упрощённом виде, библиотека расширяет их до полного объекта.

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

[
  'Kazakhstan',
  'Russia',
  'USA'
]

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

[
  { value: 'Kazakhstan', label: 'Kazakhstan' },
  { value: 'Russia', label: 'Russia' },
  { value: 'USA', label: 'USA' }
]

Если объект уже содержит value и label, он остаётся без изменений.

Поддержка пользовательских метаданных

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

{
  value: 'kz',
  label: 'Kazakhstan',
  customProperties: {
    region: 'Central Asia',
    population: 19000000
  }
}

Использование:

  • фильтрация по метаданным
  • кастомный рендеринг элементов
  • интеграция с внешними API
  • аналитика выбора

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

Формат данных также включает управляющие свойства, влияющие на поведение списка.

selected

{
  value: 'ru',
  label: 'Russia',
  selected: true
}

Используется для предустановленного выбора.

disabled

{
  value: 'us',
  label: 'United States',
  disabled: true
}

Элемент отображается, но недоступен для выбора.

placeholder

{
  value: '',
  label: 'Select country',
  placeholder: true
}

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

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

При работе с API данные обычно приходят в JSON-формате, который требует приведения к структуре Choices.js.

Пример ответа API:

[
  { "id": 1, "name": "Germany" },
  { "id": 2, "name": "France" }
]

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

fetch('/api/countries')
  .then(res => res.json())
  .then(data => {
    const formatted = data.map(item => ({
      value: item.id,
      label: item.name
    }));

    choices.setChoices(formatted, 'value', 'label', true);
  });

Работа с различными источниками данных

Статический массив

Используется при небольшом количестве данных:

choices.setChoices([
  { value: '1', label: 'One' },
  { value: '2', label: 'Two' }
]);

API-данные

Используется для динамических списков:

  • страны
  • города
  • товары
  • пользователи

DOM-данные (select/option)

Исходный HTML:

<select>
  <option value="ru">Russia</option>
  <option value="kz">Kazakhstan</option>
</select>

Choices.js преобразует их в объектную структуру автоматически.

Вложенные структуры и сложные модели

Хотя базовый формат плоский, библиотека допускает сложные структуры через группировку и вложенные массивы:

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

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

Типизация и единообразие данных

Несмотря на гибкость, Choices.js ожидает строгую консистентность:

  • value должен быть уникальным
  • label должен быть строкой
  • группы должны содержать массив choices
  • вложенные структуры не должны смешиваться с плоскими элементами

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

Преобразование и адаптация данных

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

function adaptUsers(users) {
  return users.map(user => ({
    value: user.id,
    label: `${user.firstName} ${user.lastName}`,
    customProperties: {
      email: user.email
    }
  }));
}

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

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

При работе с формами Choices.js возвращает только value выбранных элементов. Остальные поля (label, customProperties) не сериализуются автоматически и используются только на клиентской стороне.

Это делает формат данных одновременно:

  • минималистичным для отправки
  • расширяемым для интерфейса
  • независимым от backend-структуры
Оглавление