Форматирование банковских карт в Cleave.js основано на предопределённых и пользовательских шаблонах, которые определяют структуру группировки цифр, поведение ввода и правила определения типа карты. Несмотря на наличие встроенной поддержки основных платёжных систем, реальная гибкость достигается за счёт переопределения шаблонов и создания собственных масок под конкретные бизнес-требования.
В основе работы с картами в Cleave.js лежит параметр
creditCard, который включает автоматическое определение
типа карты и применение соответствующего шаблона форматирования.
Каждый шаблон представляет собой описание:
Встроенный механизм работает по следующему принципу: при вводе данных библиотека последовательно проверяет номер карты на соответствие регулярным выражениям и применяет первый подходящий шаблон.
Cleave.js позволяет переопределять стандартные шаблоны через параметр
creditCardStrictMode и пользовательский массив
creditCardType.
Структура пользовательского типа карты включает следующие поля:
type — идентификатор карты;pattern — регулярное выражение для определения
BIN-диапазона;format — массив группировки цифр;length — допустимые длины номера;cidrlength — длина CVC/CVV (если требуется расширенная
валидация);luhn — необходимость проверки алгоритмом Луна.Пример концептуальной структуры:
{
type: 'customcard',
pattern: /^9999/,
format: [4, 4, 4, 4],
length: [16],
luhn: true
}Ключевым элементом кастомизации является поле format,
которое определяет визуальную структуру номера карты.
Каждое число в массиве format обозначает длину блока
символов. Например:
[4, 4, 4, 4] — классическая 16-значная карта;[4, 6, 5] — нестандартные структуры;[4, 4, 4, 7] — расширенные форматы для корпоративных
карт.При вводе Cleave.js автоматически вставляет разделители после
достижения длины каждого блока. По умолчанию используется пробел, однако
его можно заменить через delimiter.
Параметр delimiter позволяет изменить визуальное
оформление карты без изменения логики группировки.
Поддерживаются следующие варианты:
' ') — стандартный формат;'-') — часто используется в корпоративных
системах;'.') — применяется в локальных интерфейсах;Пример конфигурации:
new Cleave(input, {
creditCard: true,
delimiter: '-'
});Изменение разделителя влияет только на отображение, но не на внутреннее значение поля, которое хранится без форматирования.
В реальных интеграциях часто требуется поддержка локальных или частных платёжных систем, которые отсутствуют в стандартной библиотеке. В таких случаях добавляются кастомные BIN-диапазоны и правила распознавания.
Основной принцип — создание точных регулярных выражений для первых цифр карты.
Пример добавления нестандартной карты:
const customCards = [
{
type: 'localpay',
pattern: /^2200/,
format: [4, 4, 4, 4],
length: [16]
}
];Далее массив передаётся в конфигурацию Cleave.js через расширенные настройки.
При наличии нескольких совпадающих шаблонов Cleave.js использует порядок приоритета:
Это означает, что при перекрывающихся диапазонах важно правильно
выстраивать структуру pattern, избегая слишком общих
выражений.
Типичная ошибка — использование широких масок вроде /^4/
для Visa-подобных карт, что может конфликтовать с более конкретными
диапазонами.
Cleave.js позволяет изменять шаблон карты после инициализации. Это особенно важно для сценариев, где тип карты определяется сервером или внешним API.
При обновлении шаблона необходимо учитывать:
Логика обновления обычно реализуется через пересоздание экземпляра или обновление конфигурации с последующим ре-инициализационным вызовом.
Некоторые платёжные системы используют длины номеров, отличные от
стандартных 16 цифр. Cleave.js поддерживает это через массив
length, который определяет допустимые варианты.
Пример:
{
type: 'extendedcard',
pattern: /^1234/,
format: [4, 4, 4, 4, 3],
length: [19]
}При этом важно учитывать, что алгоритм Луна может не применяться ко
всем типам карт, поэтому параметр luhn должен быть явно
отключён при необходимости.
Автоматическое определение типа карты основано на последовательной проверке паттернов. При добавлении кастомных шаблонов они включаются в общий пул проверки.
Особенности поведения:
Для стабилизации поведения часто используют строгие режимы, ограничивающие переключение типа карты после достижения определённой длины.
Кастомизация шаблонов должна учитывать ограничения ввода, чтобы избежать некорректных состояний. Основные меры:
length;format;Нарушение этих правил приводит к ситуации, когда вводимые данные могут «прыгать» между форматами, создавая нестабильный UX.
В корпоративных платёжных решениях часто требуется поддержка:
В таких случаях Cleave.js используется не только как форматтер, но и как слой первичной валидации структуры номера. Шаблоны становятся частью бизнес-логики интерфейса, а не просто визуальным инструментом.
Особое внимание уделяется согласованию фронтенд- и бэкенд-правил, чтобы исключить расхождения в допустимых форматах.
При вставке полного номера карты Cleave.js применяет шаблон сразу ко всему значению. Если вставленный номер не соответствует ни одному паттерну, применяется fallback-формат или базовое отображение без специфической группировки.
Автозаполнение браузера может обходить пошаговую проверку ввода, поэтому шаблоны должны быть устойчивыми к мгновенному заполнению поля.
В таких случаях ключевую роль играет корректно заданный
pattern, обеспечивающий однозначное определение типа карты
даже при отсутствии поэтапного ввода.
При большом количестве кастомных карт возрастает вероятность конфликтов между шаблонами. Для обеспечения стабильности используются следующие принципы:
Правильно настроенные шаблоны обеспечивают предсказуемое форматирование независимо от источника ввода и скорости набора данных.