Read in English

Автоматическое форматирование номеров телефонов при вводе их в поля форм значительно облегчает визуальный контроль за правильностью набора и позволяет практически избавиться от опечаток, при этом не требуя от пользователей вводить что-либо, кроме самих цифр.

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

Библиотека выполнена на чистом Javascript и совместима со всеми современными браузерами, включая Internet Explorer 11.

Как пользоваться

1. Подключить файл lib.js.

2. Составить список шаблонов телефонных номеров. Пример:

const numberPatterns = [
  '+7 (NNN) NNN-NN-NN',  // Россия и Казахстан
  '+375 NN NNN-NN-NN',   // Беларусь
  '+38 (0NN) NNN-NN-NN', // Украина
  '+1 (NNN) NNN-NNNN',   // США и Канада
];

3. Установить слежение за нужными полями. Например, за всеми полями с типом tel:

document.querySelectorAll( 'input[type=tel]' ).forEach( function( input ) {
    const formatterObject = new Freedom.PhoneFormatter( numberPatterns );
    formatterObject.attachToInput( input );
} );

(Freedom - веб-фреймворк, в рамках которого ведется разработка, отсюда и название пространства имён.)

4. Прекратить слежение, при необходимости:

formatterObject.detachFromInput();

Особенности

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

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

• если вводу не соответствует ни один шаблон, форматирование проводиться не будет

• в любом случае ввод посторонних символов (букв и пр.) подавляется

• сохраняет позицию курсора при вводе (в отличие от многих других аналогичных решений, где при любом вводе курсор прыгает в конец)

Работающий пример находится в файле docs/demo.html.

Слежение по селектору

Можно установить слежение за всеми полями, соответствующими некоторому CSS-селектору, причем не только присутствующими в настоящий момент, но и добавленными в будущем:

formatterObject.attachToSelector( 'input[type=tel]' );

Прекратить слежение: formatterObject.detachFromSelector().

Эта возможность требует подключения файла lib.js из пакета Freedom.SelectorWatcher.

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

Можно просто передать объекту номер телефона в виде строки и получить обратно строку, содержащую отформатированный номер:

console.log ( formatterObject.format( '74950000000') ); // +7 (495) 000-00-00

Если номер не соответствует ни одному из шаблонов, он будет возвращен в неизменном виде, посторонние символы не будут удалены:

console.log ( formatterObject.format( '234abc') ); // 234abc

Если передать методу true в качестве второго аргумента, в случае несовпадения он выбросит исключение:

try {
  obj.format( '234abc', true );
} catch ( e ) {
  console.log( e );
  // Phone "234abc" didn't match any of the patterns:
  // +7 (NNN) NNN-NN-NN,
  // +375 NN NNN-NN-NN,
  // +38 (0NN) NNN-NN-NN,
  // +1 (NNN) NNN-NNNN
}

true в качестве третьего аргумента включает строгую проверку на длину:

console.log ( formatterObject.format( '7495000' ) ); // +7 (495)-000 - номер отформатирован
console.log ( formatterObject.format( '7495000', undefined, true ) ); // 7495000 - номер не отформатирован

Аналог на PHP

Реализация класса на PHP имеет публичный метод format(), который работает точно так же:

$obj = new \Freedom\PhoneFormatter([
    '+7 (NNN) NNN-NN-NN',
    '+375 NN NNN-NN-NN',
    '+38 (0NN) NNN-NN-NN',
    '+1 (NNN) NNN-NNNN',
]);
echo $obj->format('74950000000'); // +7 (495) 000-00-00
echo $obj->format('7495000', null, true); // 7495000

Метод validate() предназначен для контроля корректности ввода телефона (для этого выполняется сопоставление шаблонам со строгой проверкой длины):

if (!$obj->validate($_POST['phone']) {
    $error = "Некорректный номер телефона: " . htmlspecialchars($_POST['phone']);
}

Имеется также метод keepDigitsOnly(), который удаляет из строки все символы, кроме цифр:

echo $obj::keepDigitsOnly('+7 (495) 000-00-00'); // 74950000000