Первый рабочий пример

Работа с Cleave.js начинается с подключения самой библиотеки и наличия базовой HTML-разметки, в которой будет находиться поле ввода. Библиотека предназначена для форматирования пользовательского ввода в реальном времени: номера телефонов, дат, чисел, кредитных карт и произвольных шаблонов.

Самый простой способ подключения — через CDN:

<script src="https://cdn.jsdelivr.net/npm/cleave.js@1.6.0/dist/cleave.min.js"></script>

После подключения библиотека становится доступной глобально через конструктор Cleave.

Минимальная структура страницы:

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8" />
  <title>Cleave.js пример</title>
</head>
<body>

  <input type="text" id="phone" placeholder="Введите номер" />

  <script src="https://cdn.jsdelivr.net/npm/cleave.js@1.6.0/dist/cleave.min.js"></script>
  <script>
    // инициализация будет здесь
  </script>

</body>
</html>

Инициализация первого форматирования

Базовый принцип работы Cleave.js заключается в привязке к DOM-элементу и указании типа форматирования через конфигурационный объект.

Простейший рабочий пример — форматирование номера телефона:

<script>
  const input = document.getElementById('phone');

  const cleave = new Cleave(input, {
    phone: true,
    phoneRegionCode: 'RU'
  });
</script>

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

Как работает механизм форматирования

В основе Cleave.js лежит перехват событий ввода (input, keydown, paste) и преобразование значения поля на лету. При каждом изменении:

  • текущее значение очищается от лишних символов;
  • применяется маска или правило форматирования;
  • результат записывается обратно в поле.

Это означает, что разработчику не нужно вручную обрабатывать ввод, очищать строку или следить за курсором — библиотека делает это автоматически.

Простейший пример числового форматирования

Кроме телефонов, часто требуется форматировать числа, например добавлять разделители тысяч:

<input type="text" id="number" placeholder="Введите число" />

<script>
  const numberInput = document.getElementById('number');

  const cleaveNumber = new Cleave(numberInput, {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
  });
</script>

Теперь ввод 1000000 будет автоматически отображаться как 1 000 000.

Ключевые параметры:

  • numeral: true — включает числовой режим;
  • numeralThousandsGroupStyle — задаёт стиль группировки;
  • поддерживаются разные локали и форматы разделителей.

Форматирование даты как первый практический кейс

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

<input type="text" id="date" placeholder="ДД/ММ/ГГГГ" />

<script>
  const dateInput = document.getElementById('date');

  const cleaveDate = new Cleave(dateInput, {
    date: true,
    datePattern: ['d', 'm', 'Y']
  });
</script>

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

  • автоматически вставляет разделители;
  • ограничивает диапазоны значений;
  • предотвращает ввод некорректных символов.

При вводе 01012025 результат будет преобразован в 01/01/2025.

Использование произвольных масок

Когда стандартных режимов недостаточно, применяется кастомная маска:

<input type="text" id="custom" placeholder="Код продукта" />

<script>
  const customInput = document.getElementById('custom');

  const cleaveCustom = new Cleave(customInput, {
    delimiters: ['-', '-', '/'],
    blocks: [3, 4, 2, 3],
    uppercase: true
  });
</script>

Здесь ввод разбивается на блоки фиксированной длины:

  • первые 3 символа;
  • затем 4;
  • затем 2;
  • затем 3;

Между ними автоматически вставляются разделители -, -, /.

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

преобразуется в:

ABC-1234-AB/12CDE

Работа с динамическими значениями

Cleave.js позволяет изменять поведение после инициализации через метод setRawValue:

<script>
  cleaveNumber.setRawValue('5000000');
</script>

При этом значение сразу будет отображено в отформатированном виде, без необходимости повторного ввода пользователем.

Обработка пользовательского ввода в реальном времени

Каждое изменение значения можно отслеживать через событие:

<script>
  input.addEventListener('input', function (e) {
    console.log(e.target.value);
  });
</script>

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

Типичная ошибка при первой интеграции

Часто при первом использовании возникает ситуация, когда библиотека не применяется к элементу. Основные причины:

  • скрипт подключён до загрузки DOM;
  • неверный селектор элемента;
  • повторная инициализация одного и того же поля.

Корректный порядок инициализации:

<script>
  document.addEventListener('DOMContentLoaded', function () {
    new Cleave('#phone', {
      phone: true,
      phoneRegionCode: 'RU'
    });
  });
</script>

Минимальный рабочий пример в сборе

<input type="text" id="phone" placeholder="Телефон" />
<input type="text" id="date" placeholder="Дата" />
<input type="text" id="number" placeholder="Сумма" />

<script src="https://cdn.jsdelivr.net/npm/cleave.js@1.6.0/dist/cleave.min.js"></script>

<script>
  new Cleave('#phone', {
    phone: true,
    phoneRegionCode: 'RU'
  });

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

  new Cleave('#number', {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
  });
</script>

Особенности поведения при вставке текста

При вставке (paste) Cleave.js:

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

Это позволяет безопасно вставлять данные из внешних источников без дополнительной обработки.

Важные ограничения первого уровня интеграции

На базовом уровне следует учитывать:

  • библиотека не выполняет валидацию бизнес-логики (например, существование номера телефона);
  • форматирование не заменяет проверку данных на сервере;
  • сложные сценарии могут требовать кастомных блоков и расширений.

Роль первого примера в архитектуре использования

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

Оглавление