Изменения в API между версиями

1. Структура и инициализация

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

var cleave = new Cleave('.input-phone', {
    phone: true,
    phoneRegionCode: 'US'
});

В новых версиях появилась возможность более гибкого указания настроек через маски и кастомные правила. Объект конфигурации стал более расширяемым:

const cleave = new Cleave('.input-phone', {
    delimiters: ['(', ') ', '-'],
    blocks: [0, 3, 3, 4],
    numericOnly: true
});

Ключевые изменения:

  • Полная поддержка массивов delimiters и blocks для кастомного форматирования.
  • numericOnly заменяет старый параметр numeral, предоставляя более точный контроль над числовыми значениями.

2. Форматирование чисел и валют

Ранее для чисел использовался параметр numeral: true с ограниченной функциональностью. В новых версиях добавлены возможности:

  • numeralDecimalMark – символ для десятичной части.
  • delimiter – разделитель тысяч.
  • numeralThousandsGroupStyle – стиль группировки (thousand, lakh, wan).

Пример для форматирования валюты:

const cleave = new Cleave('.input-currency', {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand',
    numeralDecimalMark: '.',
    prefix: '$',
    tailPrefix: false
});

Изменения позволяют управлять:

  • Префиксом и его положением (prefix, tailPrefix).
  • Группировкой чисел по региональным стандартам.
  • Автоматическим добавлением разделителей при наборе.

3. Обработка телефонов

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

  • phoneRegionCode теперь полностью учитывает локальные правила.
  • Добавлена возможность динамической смены региона после инициализации:
cleave.setPhoneRegionCode('GB');
  • Улучшена работа с вводом через paste, предотвращая некорректное форматирование.

4. Маски для текста

Раньше маски задавались только через blocks и delimiter. В новых версиях появилось:

  • uppercase и lowercase для автоматического преобразования.
  • Поддержка регулярных выражений для кастомных масок через blocks и blocksRegex.

Пример:

const cleave = new Cleave('.input-code', {
    blocks: [4, 4, 4],
    delimiters: ['-', '-'],
    uppercase: true
});

5. События и методы

API событий изменилось для большей унификации:

  • onValueChanged заменяет устаревший onInput и onChange:
const cleave = new Cleave('.input', {
    numeral: true,
    onValueChanged: function(e) {
        console.log(e.target.rawValue);
    }
});

  • Методы управления значением:

    • getRawValue() – возвращает значение без форматирования.
    • setRawValue(value) – устанавливает значение и автоматически форматирует его.
    • destroy() – очищает все настройки и события, возвращая исходное поле.

6. Поддержка динамических обновлений

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

cleave.properties.numeral = false;
cleave.properties.blocks = [2, 2, 2];
cleave.setRawValue('123456');
  • Изменения автоматически пересчитывают форматирование без полной переинициализации.
  • Улучшена совместимость с SPA-фреймворками, где поля создаются и удаляются динамически.

7. Устаревшие параметры

Следует учитывать, что некоторые старые опции больше не поддерживаются:

Старый параметр Новая альтернатива
numeralDecimalScale numeralDecimalMark + кастомные методы форматирования
onInput onValueChanged
blocksRegex (частично) Использование кастомных масок через delimiter и blocks
numericOnly (старый вариант) Новый numericOnly с расширенными возможностями

8. Интеграция с современными фреймворками

  • В версиях 2.x+ Cleave.js улучшил работу с React, Vue и Angular через директивы и компоненты.
  • Поддержка ref в React позволяет напрямую управлять экземпляром и его методами.
  • В Vue 3 добавлена возможность реактивного отслеживания rawValue через v-model.

9. Производительность и оптимизация

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

10. Совместимость и миграция

  • Миграция с версии 1.x на 2.x требует проверки всех устаревших параметров.
  • Основные шаги: заменить события, обновить числовое форматирование, пересмотреть маски и телефонные настройки.
  • Поддержка старых браузеров сохранена, но рекомендуется использовать последние версии для корректной работы масок и числовых форматов.
Оглавление