Телефонные маски в Cleave.js строятся на основе декларативного описания структуры номера: блоков цифр, разделителей, префиксов и правил региональной логики. Несмотря на наличие встроенной поддержки телефонов, реальные проекты почти всегда требуют расширения стандартного поведения — из-за различий национальных форматов, корпоративных шаблонов или нестандартных правил ввода.
Кастомная телефонная маска в этом контексте представляет собой конфигурацию, в которой разработчик явно контролирует:
В основе телефонной логики Cleave.js лежит разбиение строки на блоки фиксированной или переменной длины.
Типичная структура:
new Cleave(input, {
phone: true,
phoneRegionCode: 'US'
});Однако такой вариант ограничен стандартными форматами региона и не подходит для кастомных схем, например:
+7 (123) 456-78-90-01Ключевой механизм кастомизации — ручное определение структуры номера.
new Cleave(input, {
delimiters: ['(', ')', ' ', '-'],
blocks: [2, 3, 3, 2, 2],
numericOnly: true
});Массив blocks определяет, как именно вводимые цифры
группируются:
Например:
+7 (123) 456-78-90раскладывается как:
[1-2] [3] [3] [2] [2]Важный момент: Cleave.js не ограничивает длину массива blocks, что позволяет строить сложные телефонные схемы, включая корпоративные расширения.
Для телефонных масок критично правильно управлять международным префиксом.
new Cleave(input, {
prefix: '+7',
noImmediatePrefix: true,
blocks: [2, 3, 3, 2, 2],
delimiters: [' ', ' ', '-']
});prefix фиксирует начальную часть строки
noImmediatePrefix контролирует момент его
появления:
true — префикс появляется только после начала
вводаfalse — отображается сразуЭто особенно важно для UX, поскольку предотвращает ситуации, когда пользователь вынужден стирать фиксированный код страны.
В кастомных масках разделители играют не только визуальную роль, но и семантическую.
Пример:
delimiters: [' ', ' ', '-', '-']Формирует номер:
+7 777 123-45-67Разделители могут:
В Cleave.js разделители применяются строго по позиции блоков, что позволяет гарантировать предсказуемый результат независимо от скорости ввода.
Одно из ключевых требований реальных интерфейсов — смена формата в зависимости от выбранной страны или типа номера.
Подход реализуется через пересоздание экземпляра или обновление конфигурации:
let cleave = new Cleave(input, {
numericOnly: true,
blocks: [3, 3, 4],
delimiters: ['-', '-']
});
// смена формата
cleave.destroy();
cleave = new Cleave(input, {
prefix: '+44',
numericOnly: true,
blocks: [2, 4, 4],
delimiters: [' ', ' ']
});Такой подход позволяет реализовать:
Кастомные телефонные маски часто выходят за рамки стандартных конфигураций и требуют вмешательства в поток данных.
Для этого используется обработка события изменения значения:
new Cleave(input, {
numericOnly: true,
blocks: [3, 3, 4],
onValueChanged: function (e) {
const raw = e.target.rawValue;
}
});rawValue содержит чистую последовательность цифрЭто разделение критично при:
Во многих системах телефон включает добавочный номер:
+1 (212) 555-1234 x99Реализация через Cleave.js:
new Cleave(input, {
prefix: '+1',
blocks: [3, 3, 4, 2],
delimiters: [' (', ') ', '-', ' x']
});Такая структура позволяет:
Несмотря на гибкость, система масок имеет ограничения:
Нельзя напрямую задать:
Это компенсируется внешней логикой.
blocks и delimiters работают позиционно, а не контекстно.
Библиотека не понимает смысл номера — только структуру.
Для сложных систем применяется комбинация подходов:
Пример архитектурного подхода:
Пример универсального кастомного шаблона:
new Cleave(input, {
prefix: '+',
numericOnly: true,
blocks: [3, 3, 3, 4],
delimiters: [' ', ' ', ' ']
});Подходит для унифицированных систем, где:
Важная особенность Cleave.js — перерасчёт структуры при изменении любого символа внутри строки.
Это означает:
Это поведение критично для UX, поскольку предотвращает “разрушение” форматирования при редактировании.
Архитектурно кастомная маска в Cleave.js строится как комбинация:
Такой подход позволяет адаптировать библиотеку под любые телефонные стандарты без изменения её внутренней логики.