Обратная совместимость

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

Версионная стратегия Cleave.js

Библиотека придерживается семантического версионирования (SemVer). Основные принципы:

  • Мажорные версии (1.0.0 → 2.0.0) могут включать изменения, нарушающие совместимость с предыдущими версиями.
  • Минорные версии добавляют новые функции без нарушения старого API.
  • Патчи исправляют баги, сохраняя поведение всех функций.

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

Поддержка устаревших опций

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

  • numeralThousandsGroupStyle — до версии 1.5.0 поддерживалась только в ограниченном наборе стилей группировки чисел. В новых версиях используется более универсальная опция numeralGroupingStyle.
  • creditCardStrictMode — опция, отвечавшая за строгую проверку ввода номера карты, постепенно заменяется на более гибкие функции с использованием blocks и delimiters.

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

Работа с форматами ввода в разных версиях

Числовой ввод

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

new Cleave('.input-number', {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
});

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

new Cleave('.input-number', {
    numeral: true,
    numeralGroupingStyle: 'thousand'
});

Для обратной совместимости можно оставить старую опцию, так как библиотека корректно её интерпретирует.

Форматирование дат

Ранние версии Cleave.js поддерживали только базовые маски MM/DD/YYYY и DD/MM/YYYY. Новые версии добавили возможность создавать кастомные паттерны с помощью массива blocks и строки delimiter:

new Cleave('.input-date', {
    date: true,
    datePattern: ['Y', 'm', 'd']
});

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

Совместимость с браузерами

Cleave.js обеспечивает работу в современных и устаревших браузерах (IE11+). Основные моменты:

  • Полностью сохранены методы обработки input, keydown, paste.
  • Для устаревших браузеров применяются полифиллы Object.assign и Array.prototype.includes.
  • Новые функции, такие как rawValue и setRawValue, корректно работают и в старых версиях, обеспечивая единый API.

Обертки и кастомные интеграции

Многие проекты создают свои обертки вокруг Cleave.js, например, для React или Angular. Для обратной совместимости:

  • Следует проверять совместимость методов destroy(), setRawValue() и событий onValueChanged.
  • Если обертка использует старые опции, библиотека их интерпретирует, но рекомендуется постепенно переходить на новые ключи.
  • Для динамического изменения конфигурации поддерживается метод setOptions() без необходимости пересоздавать экземпляр.

Управление миграцией между версиями

Пошаговая стратегия:

  1. Аудит текущих форматов: выявление всех полей, использующих Cleave.js.
  2. Сравнение опций: сверка старых опций с актуальными ключами в новой версии.
  3. Тестирование: проверка работы полей на всех поддерживаемых браузерах.
  4. Постепенное обновление: сначала переход на минорные версии, исправление устаревших параметров, затем мажорные обновления при необходимости.

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

Примеры обратной совместимости

Старый формат чисел:

new Cleave('.input-old-number', {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
});

Совместимый новый формат:

new Cleave('.input-new-number', {
    numeral: true,
    numeralGroupingStyle: 'thousand'
});

Старый формат даты:

new Cleave('.input-old-date', {
    date: true,
    datePattern: ['m', 'd', 'Y']
});

Новый формат с кастомной маской:

new Cleave('.input-new-date', {
    date: true,
    datePattern: ['Y', 'm', 'd']
});

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

Оглавление