Базовый синтаксис и структура опций

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

const cleave = new Cleave(selectorOrElement, options);

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

  • DOM-элемент (HTMLInputElement)
  • CSS-селектор (строка)
  • Node-список (в некоторых обёртках и расширениях)

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

Пример минимальной инициализации:

const cleave = new Cleave('#phone', {
  phone: true,
  phoneRegionCode: 'RU'
});

Структура объекта опций

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

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

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

Общие управляющие параметры

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

numeral

Включает числовой режим обработки строки.

{
  numeral: true
}

При активации Cleave.js начинает интерпретировать ввод как число, автоматически применяя разделители и форматирование.

numeralDecimalMark

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

{
  numeral: true,
  numeralDecimalMark: '.'
}

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

delimiter

Устанавливает основной разделитель групп разрядов.

{
  numeral: true,
  delimiter: ' '
}

Чаще всего используется пробел, запятая или точка.

prefix

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

{
  numeral: true,
  prefix: '$'
}

Префикс отображается в поле, но не является частью логической числовой строки.

noImmediatePrefix

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

{
  prefix: '€',
  noImmediatePrefix: true
}

При включении префикс появляется только после начала ввода.

Параметры форматирования чисел

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

numeralThousandsGroupStyle

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

  • thousand
  • lakh
  • wan

Пример:

{
  numeral: true,
  numeralThousandsGroupStyle: 'thousand'
}

numeralDecimalScale

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

{
  numeral: true,
  numeralDecimalScale: 2
}

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

numeralPositiveOnly

Запрещает ввод отрицательных значений.

{
  numeral: true,
  numeralPositiveOnly: true
}

Опции работы с датами и временем

Cleave.js поддерживает форматирование дат через блоковую структуру ввода.

date

Активирует режим обработки даты.

{
  date: true
}

datePattern

Определяет порядок блоков даты:

{
  date: true,
  datePattern: ['d', 'm', 'Y']
}

Возможные элементы массива:

  • d — день
  • m — месяц
  • Y — год

delimiter (в контексте дат)

Используется как разделитель блоков даты:

{
  date: true,
  datePattern: ['Y', 'm', 'd'],
  delimiter: '-'
}

Блоковая структура ввода

Механизм блоков позволяет задавать фиксированную структуру строки.

blocks

Определяет длину каждой группы символов:

{
  blocks: [4, 4, 4, 4],
  delimiter: '-'
}

Типичный пример — банковские карты:

1234-5678-9012-3456

uppercase

Принудительное преобразование ввода в верхний регистр:

{
  blocks: [3, 3, 3],
  uppercase: true
}

lowercase

Аналогично верхнему регистру, но для нижнего:

{
  blocks: [2, 2, 2],
  lowercase: true
}

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

Один из наиболее сложных режимов Cleave.js — обработка телефонных номеров.

phone

Активирует специализированную логику форматирования:

{
  phone: true
}

phoneRegionCode

Определяет региональную маску:

{
  phone: true,
  phoneRegionCode: 'US'
}

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

Поведение и очистка данных

rawValueTrimPrefix

Определяет, удаляется ли префикс при получении «сырого» значения:

{
  prefix: '$',
  rawValueTrimPrefix: true
}

stripLeadingZeroes

Удаляет ведущие нули в числах:

{
  numeral: true,
  stripLeadingZeroes: true
}

Структура комбинированных конфигураций

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

Пример комбинированной конфигурации:

const cleave = new Cleave('#input', {
  prefix: 'ID-',
  blocks: [3, 3, 3],
  delimiter: '-',
  uppercase: true
});

Принцип интерпретации конфигурации

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

  1. Определяется специализированный режим (phone, date, numeral)
  2. Применяются правила форматирования соответствующего режима
  3. Обрабатываются дополнительные параметры (delimiter, prefix, blocks)
  4. Применяются пост-обработчики (регистры, очистка, ограничения)

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

Типовая структура объекта опций

Обобщённо конфигурация может быть представлена следующим шаблоном:

{
  // режим
  numeral: true | false,
  date: true | false,
  phone: true | false,

  // форматирование
  delimiter: string,
  blocks: number[],

  // числовые настройки
  numeralDecimalMark: string,
  numeralDecimalScale: number,
  numeralThousandsGroupStyle: string,

  // поведение
  prefix: string,
  noImmediatePrefix: boolean,
  uppercase: boolean,
  lowercase: boolean
}

Поведение при отсутствии опций

При создании экземпляра без объекта настроек Cleave.js не применяет форматирование и работает как пассивный обработчик ввода:

const cleave = new Cleave('#input');

В этом режиме изменения DOM отсутствуют, а библиотека фактически не вмешивается в поток данных.

Обработка изменений конфигурации

После инициализации объект Cleave сохраняет внутреннее состояние. Изменение опций через прямое присваивание не поддерживается. Для обновления параметров требуется переинициализация экземпляра:

cleave.destroy();

cleave = new Cleave('#input', {
  numeral: true
});
Оглавление