Базовое использование компонента

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

Инициализация начинается с создания экземпляра, привязанного к DOM-элементу input. Библиотека перехватывает события ввода и применяет правила форматирования по мере набора текста.

const cleave = new Cleave(inputElement, {
    delimiters: [' ', ' ', '-'],
    blocks: [3, 3, 2, 2],
    numericOnly: true
});

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

Подключение библиотеки

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

<script src="cleave.min.js"></script>

При использовании модульной системы:

import Cleave from 'cleave.js';

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

Создание экземпляра и привязка к input

Экземпляр создаётся один раз на каждый input-элемент. Внутри происходит подписка на события input, keydown, copy, paste.

const phoneInput = document.querySelector('#phone');

const cleavePhone = new Cleave(phoneInput, {
    phone: true,
    phoneRegionCode: 'US'
});

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

Основные параметры конфигурации

blocks

Параметр blocks определяет разбиение строки на сегменты фиксированной длины.

blocks: [4, 4, 4, 4]

Каждый элемент массива задаёт длину очередного блока символов.

delimiters

Параметр delimiters задаёт символы-разделители между блоками.

delimiters: ['-', '-', '-']

Количество разделителей должно соответствовать количеству переходов между блоками.

numericOnly

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

numericOnly: true

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

prefix

Позволяет задавать фиксированный префикс, который остаётся неизменным при вводе.

prefix: '+7'

Префикс не удаляется пользователем и всегда сохраняется в начале значения.

Режимы форматирования

Телефонный режим

Телефонный режим активируется через параметр phone.

new Cleave(inputElement, {
    phone: true,
    phoneRegionCode: 'RU'
});

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

Нумерический режим

Позволяет форматировать числа с разделителями тысяч.

new Cleave(inputElement, {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
});

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

Получение текущего значения

Значение можно получить напрямую из инстанса через свойство value.

const value = cleavePhone.getRawValue();

Метод getRawValue возвращает необработанное значение без форматирования, что важно при отправке данных на сервер.

Форматированное значение доступно через DOM-элемент:

console.log(phoneInput.value);

Обновление конфигурации

Изменение параметров возможно через метод setRawValue и повторную инициализацию.

cleavePhone.setRawValue('79991234567');

После установки нового значения библиотека автоматически применяет текущие правила форматирования.

Очистка и уничтожение экземпляра

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

cleavePhone.destroy();

После вызова destroy форматирование прекращается, а исходное поведение input восстанавливается.

Работа с событиями ввода

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

inputElement.addEventListener('input', (e) => {
    console.log(e.target.value);
});

Форматирование применяется до того, как значение становится доступным в обработчике.

Вставка и обработка paste

При вставке текста библиотека автоматически очищает и преобразует данные согласно конфигурации.

Например, при вставке строки с пробелами и символами форматирования:

+7 (999) 123-45-67

значение будет приведено к заданному шаблону без лишних символов.

Особенности внутренней обработки

В основе работы лежит механизм разбиения строки на токены и последующего пересборки с учётом правил:

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

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

Динамическое изменение значения

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

cleavePhone.setRawValue('1234567890');

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

Ограничения базового использования

Функциональность ориентирована на клиентское форматирование и не выполняет:

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

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

Оглавление