Инициализация объекта Cleave

Инициализация экземпляра Cleave представляет собой ключевой этап подключения библиотеки форматирования ввода. В этот момент создаётся связка между DOM-элементом и внутренним механизмом обработки строк, который перехватывает ввод пользователя и преобразует его в заданный формат в реальном времени.

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

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

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

const cleave = new Cleave(selectorOrElement, options);

Параметры конструктора

selectorOrElement

Принимает:

  • строку CSS-селектора ('#input', '.phone')
  • DOM-элемент (document.getElementById('input'))

options

Объект конфигурации, определяющий поведение форматирования.

Структура объекта options

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

Основные свойства

numeral

Включает режим числового форматирования.

{
  numeral: true
}

В этом режиме библиотека автоматически:

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

numeralDecimalMark

Определяет символ десятичного разделителя.

{
  numeral: true,
  numeralDecimalMark: '.'
}

Допустимые значения:

  • '.' (дефолт в англоязычных системах)
  • ',' (часто используется в европейских форматах)

delimiter

Устанавливает разделитель тысяч.

{
  numeral: true,
  delimiter: ' '
}

Пример результата:

1000000 → 1 000 000

prefix

Добавляет фиксированный префикс к значению.

{
  numeral: true,
  prefix: '$'
}

Используется для:

  • валют
  • фиксированных обозначений (например, ID форматов)

noImmediatePrefix

Управляет отображением префикса при пустом поле.

{
  numeral: true,
  prefix: '$',
  noImmediatePrefix: true
}

Если включено:

  • префикс появляется только после ввода первого символа

Инициализация числового ввода

Наиболее распространённый сценарий — форматирование денежных значений.

const priceField = new Cleave('#price', {
  numeral: true,
  numeralThousandsGroupStyle: 'thousand',
  delimiter: ',',
  numeralDecimalMark: '.',
  prefix: '$'
});

Поведение в этом режиме

При вводе:

1234567.89

Результат:

$1,234,567.89

numeralThousandsGroupStyle

Определяет стиль группировки разрядов.

Варианты

thousand

Классическая группировка по 3 цифры.

1,000,000

lakh

Используется в индийской системе счисления.

10,00,000

wan

Используется в китайской системе группировки.

100,0000

Инициализация без числового режима

Cleave.js может работать и с масками фиксированного формата, например телефонов или дат.

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

Разбор конфигурации

blocks

Определяет сегментацию строки ввода.

[0, 3, 3, 4]

означает:

  • 3 цифры
  • 3 цифры
  • 4 цифры

delimiters

Массив разделителей, вставляемых между блоками:

(XXX) XXX-XXXX

numericOnly

Ограничивает ввод только цифрами.

Поведение при инициализации

После создания экземпляра Cleave выполняет несколько внутренних операций:

1. Сканирование начального значения

Если поле уже содержит значение, оно немедленно нормализуется согласно правилам.

2. Привязка обработчиков событий

Подключаются события:

  • input
  • keydown
  • copy
  • paste

3. Создание внутреннего состояния

Библиотека хранит:

  • текущее сырое значение
  • отформатированное значение
  • позицию курсора

Обновление значения через API

После инициализации можно программно управлять значением:

cleave.setRawValue('1234567');

Особенность

Метод принимает неформатированное значение, а форматирование применяется автоматически.

Получение значений

Форматированное значение

cleave.getFormattedValue();

Сырое значение

cleave.getRawValue();

Разделение важно:

  • raw — используется для отправки на сервер
  • formatted — отображение пользователю

Повторная инициализация и ограничения

Cleave.js не предназначен для повторной инициализации одного и того же элемента без уничтожения предыдущего экземпляра.

Типичная ошибка:

new Cleave('#input', options);
new Cleave('#input', options);

Это приводит к:

  • дублированию обработчиков
  • некорректному форматированию
  • конфликту состояния

Корректный подход:

const instance = new Cleave('#input', options);
instance.destroy();

destroy()

Метод destroy() полностью отключает библиотеку от элемента.

После вызова:

  • удаляются обработчики событий
  • восстанавливается обычное поведение input
  • внутреннее состояние очищается
cleave.destroy();

Влияние начального значения

Если input содержит значение до инициализации:

<input id="price" value="1000000">

и применяется:

new Cleave('#price', {
  numeral: true,
  delimiter: ','
});

значение автоматически преобразуется в:

1,000,000

Особенности работы с пустыми значениями

При инициализации пустого поля библиотека:

  • не отображает форматирование
  • сохраняет placeholder без изменений
  • активирует форматирование только после ввода

Контекст исполнения и производительность

Инициализация Cleave.js выполняется синхронно, однако внутренняя логика оптимизирована для минимального количества перерасчётов строки.

Основные оптимизации:

  • работа без регулярных переразборов DOM
  • обработка строки в памяти
  • минимизация repaint/reflow

Типовые ошибки при создании экземпляра

Передача невалидного селектора

new Cleave('#not-exist', options);

Результат:

  • экземпляр создаётся, но не привязывается к элементу

Конфликт с другими масками

Если на input уже действует другая библиотека форматирования, возможны:

  • перехват событий
  • двойное форматирование
  • потеря курсора

Неправильная конфигурация blocks

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

  • обрезанию символов
  • невозможности ввода полного значения

Итоговая структура инициализации

Процесс создания экземпляра можно представить как последовательность:

  1. Получение DOM-элемента
  2. Разбор options
  3. Привязка событий
  4. Анализ текущего значения
  5. Первичное форматирование
  6. Активация режима перехвата ввода
Оглавление