Cleave.js поддерживает форматирование телефонных номеров с учётом международных кодов стран через встроенный механизм phone-режима, позволяющий приводить вводимые данные к единому структурированному виду без необходимости ручного парсинга или сложной валидации. Основная идея заключается в разделении номера на логические блоки, соответствующие национальным правилам нумерации, и автоматическом применении маски в зависимости от выбранной страны.
При активации телефонного режима библиотека начинает интерпретировать ввод как последовательность цифр, где первая значимая часть может рассматриваться как международный код или национальный префикс. В зависимости от конфигурации Cleave.js способен либо фиксировать страну заранее, либо определять её через параметр phoneRegionCode.
Параметр phoneRegionCode задаёт региональную привязку
номера и определяет правила разбиения строки на блоки. Например, для США
структура номера обычно соответствует шаблону
(XXX) XXX-XXXX, тогда как для стран Европы длина блоков и
их распределение может отличаться.
Внутри Cleave.js это выражается следующим образом:
Ключевой особенностью является то, что библиотека не просто визуально форматирует строку, а применяет заранее определённые маски, соответствующие выбранному региону, что снижает вероятность некорректного ввода.
В международных форматах первым элементом номера выступает код
страны, начинающийся с символа +. Cleave.js обрабатывает
его как часть строки, но логически отделяет от основного номера.
При вводе международного номера происходит следующая последовательность обработки:
+ как маркера международного
формата;Важно, что библиотека не выполняет полноценную валидацию соответствия кода страны и номера — она лишь структурирует ввод. Это позволяет использовать Cleave.js совместно с внешними библиотеками валидации, такими как libphonenumber, для более строгой проверки.
Механизм префиксов в Cleave.js тесно связан с параметром
prefix. Он используется для автоматического добавления
символов или кодов в начало строки, включая международный +
или фиксированный код страны.
Пример логики обработки:
Такой подход особенно полезен в формах, где страна уже известна заранее и не требует выбора пользователем.
Телефонные номера в Cleave.js разбиваются на блоки, определяемые
параметром blocks. Хотя этот параметр чаще используется для
кастомных масок, он также влияет на отображение международных форматов
при ручной настройке.
Например, структура может быть задана как последовательность:
Разделение блоков позволяет:
При этом длина блоков может изменяться динамически, если используется режим автодетекта региона.
В сложных интерфейсах часто требуется переключение страны без очистки поля ввода. Cleave.js поддерживает сценарии, в которых изменяется только региональная логика, а уже введённые данные перерасчитываются под новую маску.
Такой механизм реализуется через пересоздание экземпляра или обновление конфигурации, где:
phoneRegionCode;Особое внимание требуется при смене страны с различной длиной номера, поскольку часть данных может оказаться избыточной или недостаточной для новой маски.
В процессе ввода международного номера часто возникает ситуация, когда код страны введён частично или отсутствует. Cleave.js в этом случае не блокирует ввод, а продолжает интерпретацию строки как локального номера до появления признака международного формата.
Логика обработки выглядит следующим образом:
+ трактуется как локальный ввод;+ переключает режим интерпретации;Такой подход обеспечивает устойчивость интерфейса к незавершённым вводам и снижает необходимость предварительного выбора страны.
Cleave.js не выполняет проверку корректности телефонных кодов стран на уровне стандартов ITU. Поэтому его часто комбинируют с библиотеками, которые предоставляют полную модель телефонного плана.
В типичной архитектуре Cleave.js отвечает за:
Валидация же переносится на внешний слой, где проверяются:
Это разделение ответственности позволяет сохранить лёгкость Cleave.js и одновременно обеспечить строгую проверку данных.
Некоторые страны используют нестандартные или изменяемые форматы нумерации. В таких случаях фиксированные маски могут оказаться недостаточными. Cleave.js предоставляет возможность частичной кастомизации через ручное определение блоков и отключение автоматического форматирования.
Подобные сценарии включают:
При этом гибкость конфигурации позволяет моделировать такие форматы вручную, сохраняя при этом поведение библиотеки для стандартных случаев.
Удаление международного префикса влияет на внутреннее состояние
форматирования. При стирании + или кода страны Cleave.js
пересчитывает структуру номера и возвращает его к локальному виду.
При редактировании возможны следующие сценарии:
+ восстанавливает международный
режим;Такая динамика требует аккуратного взаимодействия с пользовательским вводом в интерфейсах с автодополнением.
При комбинировании телефонного режима с пользовательскими масками
возникает приоритет региональной логики. Если задан
phoneRegionCode, он может переопределять ручные настройки
блоков.
В случаях конфликтов:
Такой механизм обеспечивает согласованность отображения номера независимо от сложности конфигурации.