Встроенная валидация

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

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

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

Одним из базовых механизмов встроенной валидации выступает ограничение числа выбранных значений.

maxItemCount

Параметр maxItemCount задаёт верхний предел количества выбранных элементов:

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

Типичный сценарий — мультиселекты с фиксированным числом ответов (например, выбор до 3 тегов).

new Choices('#example', {
  maxItemCount: 3
});

Поведение системы в этом режиме:

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

Ограничение длины текстового значения

maxItemTextLength

Параметр maxItemTextLength ограничивает длину вводимого или добавляемого элемента.

Используется в сценариях:

  • тегирования
  • пользовательских меток
  • ввода пользовательских значений
new Choices('#tags', {
  maxItemTextLength: 20
});

Механика работы:

  • при превышении длины строка отклоняется до добавления
  • значение не попадает в список выбранных элементов
  • ввод остаётся в поле, но не фиксируется как выбранный элемент

Это позволяет предотвращать перегрузку интерфейса слишком длинными значениями и поддерживать единый визуальный формат.

Запрет дубликатов

duplicateItemsAllowed

Контроль повторяющихся значений реализуется через параметр duplicateItemsAllowed.

new Choices('#select', {
  duplicateItemsAllowed: false
});

Логика:

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

Особенно важно в сценариях:

  • выбор категорий
  • фильтрация тегов
  • работа с множественными связями

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

addItemFilter

Наиболее гибкий механизм встроенной валидации — функция addItemFilter, позволяющая перехватывать добавление элемента и принимать решение о допустимости значения.

new Choices('#input', {
  addItemFilter: (value) => {
    return /^[a-zA-Z0-9_]+$/.test(value);
  }
});

Поведение:

  • функция вызывается перед добавлением элемента
  • возвращаемое значение true разрешает добавление
  • false блокирует вставку

Типовые сценарии использования

  • ограничение по регулярному выражению (только латиница, цифры)
  • запрет пробелов
  • проверка доменных имён
  • фильтрация нежелательных символов

Валидация пользовательского ввода в режиме тегов

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

Встроенный механизм работает на нескольких уровнях:

  1. фильтрация символов через addItemFilter
  2. ограничение длины через maxItemTextLength
  3. контроль количества через maxItemCount
  4. предотвращение дублей через duplicateItemsAllowed

Комбинация этих параметров формирует базовый валидатор без внешних библиотек.

Поведение при программном добавлении элементов

Валидация применяется не только к пользовательскому вводу, но и к API-методам:

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

instance.setValue([{ value: 'test', label: 'Test' }]);

При программном добавлении действуют те же ограничения:

  • превышение maxItemCount блокирует добавление
  • addItemFilter может отклонить значение
  • дубликаты игнорируются при соответствующей настройке

Это обеспечивает единообразие поведения независимо от источника данных.

Обработка некорректных значений

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

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

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

Валидация через события жизненного цикла

Дополнительный уровень контроля обеспечивается событиями:

  • addItem
  • removeItem
  • change
  • invalid

С их помощью можно реализовать внешнюю проверку:

const el = document.querySelector('#select');

el.addEventListener('addItem', (event) => {
  const value = event.detail.value;

  if (value.includes('admin')) {
    event.preventDefault();
  }
});

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

Ограничения встроенной системы валидации

Встроенная модель валидации ориентирована на UI-уровень и не заменяет полноценную бизнес-валидацию:

  • отсутствует проверка асинхронных условий (например, запросов к серверу)
  • нет встроенной схемной валидации (JSON Schema и аналоги)
  • нет контекстных зависимостей между полями формы

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

Оглавление