Обработчик onCreditCardTypeChanged

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

В Cleave.js определение типа банковской карты основано на анализе введённых цифр номера и сопоставлении с известными BIN-префиксами. При каждом изменении значения поля библиотека пересчитывает возможный тип карты и при необходимости вызывает специальный обработчик onCreditCardTypeChanged.

Этот механизм встроен в модуль credit card mode и работает поверх стандартного форматирования номера, разделяя ответственность между визуальным представлением и логикой определения типа.

Тип карты может изменяться динамически в процессе ввода, поскольку первые несколько цифр уже позволяют предположить эмитента, но окончательная идентификация уточняется по мере увеличения длины номера.

Сигнатура и поведение callback

Обработчик onCreditCardTypeChanged вызывается каждый раз, когда вычисленный тип карты отличается от предыдущего значения.

Функциональная сигнатура:

onCreditCardTypeChanged: function (type) {}

Параметр type представляет собой строку, содержащую идентификатор карты или специальное значение unknown, если тип не определён.

Типичные значения:

  • visa
  • mastercard
  • amex
  • discover
  • diners
  • jcb
  • unknown

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

Инициализация Cleave.js с отслеживанием типа карты

Подключение обработчика осуществляется через конфигурацию экземпляра Cleave:

const creditCard = new Cleave('#card-number', {
    creditCard: true,
    onCreditCardTypeChanged: function (type) {
        console.log('Detected card type:', type);
    }
});

При вводе номера, например 4111, 5111, 3782, библиотека будет последовательно менять тип и вызывать callback только при переходах между различными состояниями.

Внутренний процесс детекции

Алгоритм определения типа карты основан на следующих этапах:

  1. Очистка входной строки от нецифровых символов
  2. Сопоставление префикса с таблицей BIN-диапазонов
  3. Проверка диапазонов длины номера
  4. Переклассификация при каждом изменении значимых цифр

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

Практическое использование в UI

Основное применение onCreditCardTypeChanged связано с динамическим обновлением интерфейса:

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

Пример переключения логотипа:

const icons = {
    visa: 'visa-icon',
    mastercard: 'mc-icon',
    amex: 'amex-icon',
    unknown: 'default-icon'
};

const creditCard = new Cleave('#card-number', {
    creditCard: true,
    onCreditCardTypeChanged: function (type) {
        const icon = document.querySelector('.card-icon');

        icon.className = '';
        icon.classList.add(icons[type] || icons.unknown);
    }
});

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

Поведение при неполных данных

На ранних стадиях ввода номер карты часто недостаточен для точного определения типа. В таких случаях библиотека возвращает unknown.

Это состояние важно учитывать как нормальное, а не как ошибку. При дальнейшем вводе тип может уточняться.

Особенность заключается в том, что переход возможен в обе стороны:

  • unknown → visa
  • visa → unknown (при удалении символов)
  • visa → mastercard (при изменении префикса)

Каждый переход инициирует вызов обработчика.

Особенности работы с удалением символов

При удалении цифр логика пересчитывает тип карты с нуля на основе оставшегося значения. Это означает, что:

  • сокращение номера может привести к потере идентификации
  • повторное введение символов снова инициирует детекцию
  • callback может вызываться несколько раз при редактировании

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

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

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

Типичная схема интеграции:

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

Пример:

let currentType = 'unknown';

const creditCard = new Cleave('#card-number', {
    creditCard: true,
    onCreditCardTypeChanged: function (type) {
        currentType = type;
        updateValidationRules(type);
    }
});

function updateValidationRules(type) {
    if (type === 'amex') {
        console.log('Set AMEX rules: 15 digits');
    } else if (type === 'visa') {
        console.log('Set VISA rules: 16 digits');
    }
}

Производительность и частота вызовов

Несмотря на то, что ввод символов может происходить очень часто, Cleave.js оптимизирует вызовы callback:

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

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

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

В сложных формах обработки платежей onCreditCardTypeChanged применяется для:

  • переключения провайдеров эквайринга
  • динамической подгрузки комиссий
  • изменения placeholder и подсказок
  • ограничения допустимых BIN-диапазонов

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

function restrictByType(type) {
    if (type === 'amex') {
        console.log('Allow only 15-digit flow');
    }
}

Особенности поведения при автозаполнении

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

В таких случаях callback вызывается один раз после полной обработки значения, а не поэтапно.

Это важно учитывать при синхронизации UI, поскольку визуальные изменения могут происходить скачкообразно.

Совместимость с другими режимами Cleave.js

onCreditCardTypeChanged работает исключительно в режиме:

creditCard: true

В других режимах (numeric, date, custom delimiter) этот callback не активируется, поскольку отсутствует логика BIN-анализа.

При переключении режима экземпляра Cleave необходимо учитывать, что состояние типа карты сбрасывается.

Типичные ошибки при использовании

Наиболее распространённые проблемы:

  • попытка использовать callback вне creditCard-режима
  • предположение, что type всегда валиден (игнорирование unknown)
  • хранение типа без учёта возможности обратного изменения
  • привязка критической бизнес-логики только к этому событию

Корректная архитектура предполагает использование onCreditCardTypeChanged только как сигнала, а не как источника финальной валидации.

Поведение при нестандартных BIN-диапазонах

Некоторые корпоративные или локальные карты могут не попадать в стандартную классификацию Cleave.js. В таких случаях:

  • тип остаётся unknown
  • callback может не переходить в известное состояние
  • требуется внешняя кастомная логика определения

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

Оглавление