autoUnmask

Параметр autoUnmask в библиотеке Inputmask управляет тем, в каком виде значение поля ввода возвращается из DOM-элемента и API библиотеки: в замаскированном (форматированном) или в «чистом» (безмасочном) виде.

Основная идея заключается в автоматическом преобразовании значения при обращении к свойству value, а также при взаимодействии с формами и методами получения данных.

Поведение autoUnmask

При включённом autoUnmask библиотека изменяет стандартную модель работы с input-значением:

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

Это влияет на все операции чтения значения из поля ввода, включая:

  • input.value
  • jQuery .val()
  • сериализацию формы
  • внутренние методы Inputmask

Базовая конфигурация

Inputmask({
  mask: "9999-9999-9999-9999",
  autoUnmask: true
}).mask("#card");

При такой настройке поле отображает ввод в формате кредитной карты:

1234-5678-9012-3456

Но фактическое значение, которое возвращается при чтении:

1234567890123456

Разница между autoUnmask и unmaskedvalue()

В Inputmask существует несколько способов получить «чистое» значение:

autoUnmask

Автоматически влияет на поведение value:

input.value

unmaskedvalue()

Явный метод получения необработанного значения:

Inputmask().unmaskedvalue(input);

или через экземпляр:

let im = Inputmask("9999-9999");
im.mask(input);

im.unmaskedvalue(input);

Сравнение поведения

Режим input.value unmaskedvalue()
autoUnmask: false 1234-5678 12345678
autoUnmask: true 12345678 12345678

Поведение при отправке формы

Одно из ключевых применений autoUnmask — контроль данных, отправляемых на сервер.

Без autoUnmask

<input id="phone" value="+7 (999) 123-45-67">

При отправке формы сервер получает:

+7 (999) 123-45-67

С autoUnmask

Inputmask({
  mask: "+7 (999) 999-99-99",
  autoUnmask: true
}).mask("#phone");

Форма отправляет:

79991234567

Влияние на DOM-свойство value

Ключевая особенность autoUnmask — перехват чтения значения.

Внутри Inputmask реализуется логика, при которой:

  • визуально в input остаётся маска;
  • при чтении .value возвращается очищенное значение;
  • при записи .value применяется обратное форматирование.

Это делает поведение поля «прозрачным» для кода, который не учитывает маску.

Использование с jQuery

Inputmask часто используется совместно с jQuery, и autoUnmask влияет на .val():

$("#phone").inputmask({
  mask: "999-999-9999",
  autoUnmask: true
});

console.log($("#phone").val());

Результат:

9999999999

При отключённом режиме:

999-999-9999

Особенности поведения при частичном вводе

Если поле заполнено не полностью, autoUnmask может возвращать:

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

Пример:

Inputmask({
  mask: "9999-9999",
  autoUnmask: true
}).mask("#code");

Ввод:

12__-____

Результат:

12

(незаполненные позиции отбрасываются)

Влияние на placeholder и showMaskOnFocus

autoUnmask работает независимо от визуальных параметров:

  • placeholder
  • showMaskOnFocus
  • showMaskOnHover

Маска может отображаться полностью или частично, но возвращаемое значение всё равно будет очищено.

Использование с динамическими масками

При динамических масках поведение становится более контекстным:

Inputmask({
  mask: ["999-999", "9999-9999"],
  autoUnmask: true
}).mask("#field");

В зависимости от введённых данных:

  • отображение может переключаться между форматами;
  • возвращаемое значение всегда будет без разделителей.

Сценарии применения

Хранение данных в базе

Используется для унификации хранения:

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

В базе сохраняется только «чистая» строка.

Валидация на стороне сервера

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

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

При отправке JSON:

fetch("/api", {
  method: "POST",
  body: JSON.stringify({
    phone: document.querySelector("#phone").value
  })
});

При autoUnmask: true сервер получает уже нормализованное значение без дополнительных преобразований.

Ограничения и нюансы

Потеря форматированной информации

После включения autoUnmask невозможно получить оригинальную строку с маской через value. Для этого требуется:

  • либо отключить autoUnmask,
  • либо хранить значение отдельно.

Поведение при программной установке значения

input.value = "12345678";

При включённом autoUnmask Inputmask может:

  • интерпретировать значение как уже очищенное;
  • применить маску поверх него при следующем обновлении;
  • или оставить как есть, если формат совпадает с ожиданиями маски.

Конфликты с сериализацией форм

Некоторые библиотеки сериализации форм могут игнорировать Inputmask-логику и читать DOM напрямую. В таких случаях важно учитывать, что:

  • autoUnmask влияет только на доступ через Inputmask/обёртки;
  • низкоуровневое чтение DOM может возвращать другое значение в зависимости от момента обращения.

Взаимодействие с других опциями Inputmask

autoUnmask часто используется совместно с:

  • removeMaskOnSubmit — дополнительная очистка при отправке формы;
  • clearMaskOnLostFocus — изменение отображения при потере фокуса;
  • nullable — управление пустыми значениями;
  • greedy — контроль заполнения маски.

Комбинация этих параметров определяет, насколько «строго» Inputmask работает с форматированием и хранением данных.

Типичные ошибки использования

Ожидание сохранения маски

Разработчики часто предполагают, что маска сохраняется в value. При autoUnmask: true это не так — значение всегда очищено.

Двойная очистка

Если одновременно использовать:

  • autoUnmask: true
  • ручную функцию очистки

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

Неправильная обработка на сервере

Сервер иногда ожидает форматированное значение, например:

+7 (999) 123-45-67

но получает:

79991234567

что может нарушить бизнес-логику, если формат важен.

Логическая модель работы

autoUnmask можно рассматривать как переключатель уровня представления данных:

  • UI слой: отображает маску
  • DOM слой: возвращает чистое значение
  • серверный слой: получает нормализованные данные

Таким образом, библиотека переносит ответственность за форматирование с уровня данных на уровень отображения.

Оглавление