Переход с более ранних версий

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

Конструктор Cleave

В ранних версиях конструктор принимал один объект с параметрами. В актуальных версиях поддерживается тот же синтаксис, однако структура некоторых параметров изменилась:

// Старый синтаксис
var cleave = new Cleave('.input', {
    creditCard: true
});

// Новый синтаксис
var cleave = new Cleave('.input', {
    creditCard: true,
    onValueChanged: function(e) {
        console.log(e.target.value);
    }
});

Ключевое отличие: методы обратного вызова и обработчики событий стали более гибкими, теперь можно подписываться на изменение значения через onValueChanged, что не поддерживалось в версиях до 1.5.

Опции форматирования

Ряд опций был переименован или заменён:

delimiterLazyShow → delimitersOnPaste (управление автоматическим вставлением разделителей при вставке текста)
blocks теперь всегда принимает массив чисел, даже для единичного блока.
numericOnly заменён на numeric с булевым значением.

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

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

Модуль форматирования кредитных карт был переработан для большей точности и поддержки новых типов карт. В старых версиях creditCard: true автоматически определял тип карты и форматировал номер. Теперь следует использовать дополнительные методы:

var cleave = new Cleave('.input', {
    creditCard: true,
    onCreditCardTypeChanged: function(type) {
        console.log('Тип карты:', type);
    }
});

Особенности:

Детекция типа карты стала асинхронной при больших объёмах данных.
Форматирование учитывает пробелы и дефисы в зависимости от стандарта ISO 7812.
Для кастомных шаблонов карт нужно явно задавать blocks и delimiter.

Числовое и денежное форматирование

С переходом на новые версии изменился синтаксис опций для чисел и валют:

numeralDecimalMark → decimalMark
numeralThousandsGroupStyle → thousandsGroupStyle
prefix и suffix теперь могут принимать функции для динамического изменения в зависимости от вводимого значения.

Пример:

var cleave = new Cleave('.input', {
    numeral: true,
    numeralDecimalMark: '.',
    delimiter: ',',
    numeralThousandsGroupStyle: 'thousand'
});

В новой версии:

var cleave = new Cleave('.input', {
    numeral: true,
    decimalMark: '.',
    delimiter: ',',
    thousandsGroupStyle: 'thousand'
});

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

Маски для телефонов

Форматирование телефонов стало более гибким: теперь можно использовать шаблоны с переменной длиной номера и несколькими масками:

var cleave = new Cleave('.input', {
    phone: true,
    phoneRegionCode: 'RU',
    onValueChanged: function(e) {
        console.log('Номер телефона:', e.target.value);
    }
});

Изменения по сравнению с более ранними версиями:

phoneRegionCode заменяет старую phoneFormatter.
Поддержка динамических масок для международных номеров.
Метод getFormattedValue() корректно возвращает значение с учетом всех масок.

Методы работы с экземпляром

Некоторые методы были переименованы или изменили сигнатуру:

Старый метод	Новый метод	Изменение
`getRawValue()`	`getRawValue()`	Сохранил имя, поведение идентично
`setRawValue(value)`	`setRawValue(value)`	Поведение идентично, но теперь поддерживает все типы форматирования
`destroy()`	`destroy()`	Очистка событий и форматирования стала безопаснее и предотвращает утечки памяти

Обработка событий

Ранее использовались собственные обработчики DOM (onInput, onChange). В новых версиях предпочтительнее использовать встроенные обратные вызовы:

onValueChanged — срабатывает при любом изменении значения, включая вставку и удаление.
onCreditCardTypeChanged — срабатывает при изменении типа карты.
onInit — срабатывает после инициализации, полезно для динамической подгрузки данных.