Методы работы с данными

Внутренняя модель данных Choices.js

Choices.js строит работу вокруг двух ключевых сущностей: choices (варианты выбора) и items (выбранные значения). Независимо от источника данных — HTML <select>, массива объектов или удалённого API — библиотека нормализует данные в единый внутренний формат.

Каждый элемент choices обычно представлен структурой:

  • value — уникальный идентификатор
  • label — отображаемый текст
  • selected — состояние выбора
  • disabled — доступность
  • дополнительные поля (customProperties, placeholder, group)

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

Инициализация и первичная загрузка данных

При создании экземпляра Choices.js данные могут поступать из нескольких источников:

Инициализация через HTML

const element = document.querySelector('#select');
const choices = new Choices(element);

В этом случае библиотека парсит <option> и <optgroup> и строит внутреннюю коллекцию.

Инициализация через JavaScript

const choices = new Choices('#select', {
  choices: [
    { value: 'js', label: 'JavaScript' },
    { value: 'py', label: 'Python' }
  ]
});

Этот способ полностью заменяет исходный DOM-набор.

Инициализация с группировкой

choices.setChoices([
  {
    label: 'Frontend',
    choices: [
      { value: 'react', label: 'React' },
      { value: 'vue', label: 'Vue' }
    ]
  }
]);

Группы позволяют структурировать данные без изменения логики выбора.

Метод setChoices: основа управления списком вариантов

Назначение метода

setChoices используется для загрузки или перезагрузки списка доступных вариантов. Он может:

  • полностью заменить текущие choices
  • добавить новые элементы
  • загрузить данные асинхронно

Сигнатура

setChoices(choicesArray, valueKey, labelKey, replaceChoices)
  • choicesArray — массив данных
  • valueKey — ключ значения (по умолчанию value)
  • labelKey — ключ отображаемого текста (по умолчанию label)
  • replaceChoices — флаг замены текущего списка

Полная замена данных

choices.setChoices(
  [
    { value: 'html', label: 'HTML' },
    { value: 'css', label: 'CSS' }
  ],
  'value',
  'label',
  true
);

При replaceChoices = true старые данные полностью удаляются из внутреннего store.

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

choices.setChoices([
  { value: 'node', label: 'Node.js' }
], 'value', 'label', false);

Используется при догрузке данных, например, при пагинации.

Метод setChoiceByValue: выбор значений программно

Назначение

Позволяет установить выбранные элементы на основе их значения.

Сигнатура

setChoiceByValue(value)

или массив значений:

setChoiceByValue(['js', 'py'])

Пример использования

choices.setChoiceByValue('react');

или множественный выбор:

choices.setChoiceByValue(['react', 'vue']);

Метод автоматически синхронизирует:

  • внутренний store
  • отображение в UI
  • состояние выбранных items

Метод clearStore: полная очистка состояния

Назначение

Полностью очищает внутренние данные Choices.js, включая:

  • список choices
  • выбранные items
  • фильтры поиска
  • состояние dropdown

Сигнатура

clearStore()

Пример

choices.clearStore();

После выполнения экземпляр становится «пустым», как при инициализации без данных.

Метод clearChoices: очистка только списка вариантов

Назначение

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

Сигнатура

clearChoices()

Поведение

  • choices → пусто
  • items → сохраняются
  • UI → обновляется

Пример

choices.clearChoices();

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

Метод clearInput: очистка строки поиска

Назначение

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

Сигнатура

clearInput()

Пример

choices.clearInput();

Полезно после программного изменения списка или выбора значения.

Методы получения данных

getValue: получение выбранных значений

Метод возвращает текущие выбранные элементы.

Сигнатура

getValue()

Поведение

Возвращает массив объектов:

[
  { value: 'js', label: 'JavaScript', selected: true }
]

Получение только значений

В некоторых конфигурациях можно получить упрощённый массив:

choices.getValue(true);

Результат:

['js', 'py']

Работа с единичным значением

Если Choices.js используется как single select, getValue() возвращает один объект:

{
  value: 'react',
  label: 'React',
  selected: true
}

Манипуляции с отдельными элементами

addChoice: добавление нового варианта

Сигнатура

addChoice(choices, value, label, select = false, customProperties)

Пример

choices.addChoice(
  { value: 'svelte', label: 'Svelte' },
  'value',
  'label',
  false
);

Автовыбор при добавлении

choices.addChoice(
  { value: 'solid', label: 'SolidJS' },
  'value',
  'label',
  true
);

removeChoice: удаление элемента

Удаляет вариант по значению.

choices.removeChoice('react');

При удалении:

  • элемент исчезает из dropdown
  • снимается выбор, если он был активен
  • обновляется store

Работа с данными в async-режиме

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

Пример загрузки данных

fetch('/api/languages')
  .then(res => res.json())
  .then(data => {
    choices.setChoices(data, 'id', 'name', true);
  });

Постепенная загрузка (lazy loading)

fetch('/api/languages?page=2')
  .then(res => res.json())
  .then(data => {
    choices.setChoices(data, 'id', 'name', false);
  });

Обновление существующих данных

Choices.js не предоставляет прямого updateChoice, но обновление реализуется через комбинацию методов:

Подход через remove + add

choices.removeChoice('react');

choices.addChoice({
  value: 'react',
  label: 'React 19'
});

Полная перезагрузка через setChoices

choices.setChoices(newData, 'value', 'label', true);

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

Работа с группированными данными

Choices.js поддерживает вложенные структуры.

Структура группы

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

Загрузка групп

choices.setChoices(groupedData);

Группы обрабатываются как отдельные контейнеры внутри store, но сохраняют ту же модель value/label.

Валидация данных при работе с API

При динамической загрузке важно учитывать:

  • уникальность value
  • наличие label
  • отсутствие null значений
  • корректный тип (строка или число)

Choices.js не выполняет строгую валидацию, поэтому некорректные данные могут привести к:

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

Внутреннее состояние и синхронизация

Каждый метод, работающий с данными, синхронизирует три слоя:

  • store (внутреннее состояние)
  • DOM (select + dropdown)
  • UI state (selected items, search input)

Например, setChoiceByValue одновременно:

  • обновляет items
  • отмечает selected флаг у choice
  • пересчитывает отображение

Комбинирование методов для сложных сценариев

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

const selected = choices.getValue(true);

choices.setChoices(newData, 'value', 'label', true);
choices.setChoiceByValue(selected);

Очистка интерфейса перед новой загрузкой

choices.clearStore();

fetch('/api/new-data')
  .then(res => res.json())
  .then(data => {
    choices.setChoices(data, 'value', 'label', true);
  });

Динамическое добавление с предотвращением дубликатов

const exists = choices.getValue(true).includes('react');

if (!exists) {
  choices.addChoice({
    value: 'react',
    label: 'React'
  });
}

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

  • изменения всегда немедленно отражаются в UI
  • store является единственным источником истины
  • DOM не используется как источник данных после инициализации
  • порядок элементов зависит от порядка в массиве choices
  • группировка не влияет на уникальность value

Ограничения модели данных

Choices.js не поддерживает:

  • вложенные уровни глубже второго (группы + элементы)
  • сложные связи между choices
  • реактивные обновления как в framework-решениях

Все операции выполняются императивно через API методов.

Оглавление