Создание переиспользуемых конфигураций

Библиотека распространяется через npm и CDN и может использоваться как в классическом JavaScript, так и в современных фреймворках.

Установка через npm

npm install cleave.js

Подключение через ES Modules

import Cleave fr om 'cleave.js';
import 'cleave.js/dist/addons/cleave-phone.i18n';

Подключение через CDN

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

Базовая инициализация

Cleave.js работает поверх обычного <input> и форматирует ввод в реальном времени.

<input type="text" id="input" />
const cleave = new Cleave('#input', {
  delimiters: ['-'],
  blocks: [3, 3, 3],
  uppercase: true
});

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

  • delimiters — символы-разделители
  • blocks — группы символов
  • uppercase / lowercase — трансформация регистра

Форматирование телефонных номеров

Одна из самых популярных задач — форматирование телефонов.

new Cleave('#phone', {
  phone: true,
  phoneRegionCode: 'US'
});

Для других регионов используется подключаемый модуль:

import 'cleave.js/dist/addons/cleave-phone.ru';
new Cleave('#phone', {
  phone: true,
  phoneRegionCode: 'RU'
});

Форматирование банковских карт

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

new Cleave('#card', {
  creditCard: true
});

Поддерживаемые карты:

  • Visa
  • MasterCard
  • American Express
  • Discover

Расширенная настройка:

new Cleave('#card', {
  creditCard: true,
  onCreditCardTypeChanged: function (type) {
    console.log('Card type:', type);
  }
});

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

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

Варианты шаблонов:

  • d-m-Y
  • m-d-Y
  • Y-m-d

Числовые форматы

Cleave.js поддерживает форматирование чисел с разделителями тысяч и десятичной частью.

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

Дополнительные опции:

new Cleave('#number', {
  numeral: true,
  numeralDecimalMark: '.',
  delimiter: ',',
  numeralDecimalScale: 2
});

Работа с блоками (blocks & delimiters)

Механизм блоков лежит в основе гибкого форматирования.

new Cleave('#code', {
  blocks: [4, 4, 4, 4],
  delimiters: [' ', ' ', ' ']
});

Пример использования:

  • ввод банковских идентификаторов
  • серийные ключи
  • коды подтверждения

Динамическое изменение опций

Экземпляр можно обновлять без пересоздания.

const cleave = new Cleave('#input', {
  numeral: true
});

cleave.setRawValue('12345');

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

cleave.properties.numeral = false;
cleave.init();

Получение и установка значений

Cleave.js хранит два типа значений:

  • raw value — чистое значение
  • formatted value — отображаемое значение

Получение raw value

cleave.getRawValue();

Установка значения

cleave.setRawValue('999888777');

Событие изменения

new Cleave('#input', {
  numeral: true,
  onValueChanged: function (e) {
    console.log(e.target.value);
    console.log(e.target.rawValue);
  }
});

Структура события:

  • value — отформатированное значение
  • rawValue — чистое значение
  • target — DOM-элемент

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

cleave.destroy();

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

  • форматирование отключается
  • input возвращается к стандартному поведению

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

const inputs = document.querySelectorAll('.phone');

const instances = Array.from(inputs).map(input => {
  return new Cleave(input, {
    phone: true,
    phoneRegionCode: 'US'
  });
});

Валидация и ограничения ввода

Cleave.js не является валидатором, но может ограничивать ввод через форматирование.

Пример ограничения на цифры:

new Cleave('#code', {
  numeral: true,
  numeralPositiveOnly: true
});

Кастомные форматы

new Cleave('#custom', {
  blocks: [2, 2, 2, 2],
  delimiters: ['-', '-', '-'],
  numericOnly: true
});

Применения:

  • промокоды
  • артикулы
  • внутренние идентификаторы

Интеграция с React

import React, { useEffect, useRef } from 'react';
import Cleave from 'cleave.js';

function PhoneInput() {
  const ref = useRef(null);

  useEffect(() => {
    const cleave = new Cleave(ref.current, {
      phone: true,
      phoneRegionCode: 'US'
    });

    return () => cleave.destroy();
  }, []);

  return <input ref={ref} />;
}

Интеграция с формами

const form = document.querySelector('form');

form.addEventListener('submit', (e) => {
  const cleave = new Cleave('#input', { numeral: true });

  console.log(cleave.getRawValue());
});

Производительность при большом количестве инстансов

При работе с множеством полей форматирования важно учитывать:

  • минимизацию повторной инициализации
  • избегание частых destroy/init
  • использование делегирования событий вне библиотеки

Частые сценарии применения

Финансовые данные

  • суммы
  • IBAN
  • номера карт

Коммуникации

  • телефоны
  • коды подтверждения

Системные идентификаторы

  • серийные ключи
  • UUID-подобные строки

Ограничения модели форматирования

Cleave.js работает только на уровне представления ввода и не:

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

Форматирование всегда отделено от бизнес-логики приложения.

Поведение при вставке текста

При вставке значения:

  • строка очищается от лишних символов
  • применяется текущая маска
  • блоки пересчитываются заново
new Cleave('#input', {
  blocks: [3, 3, 3]
});

Работа с кастомными обработчиками

new Cleave('#input', {
  numeral: true,
  onValueChanged: function(e) {
    if (e.target.rawValue.length > 10) {
      console.log('Lim it reached');
    }
  }
});

Комбинирование форматов

Некоторые сценарии требуют комбинированного подхода:

new Cleave('#input', {
  numeral: true,
  numeralThousandsGroupStyle: 'thousand',
  prefix: '$'
});

Поведение при удалении символов

Cleave.js пересчитывает блоки динамически:

  • удаление в середине строки приводит к переразметке
  • разделители автоматически корректируются
  • raw value остаётся непрерывным числом/строкой
Оглавление