onUnMask

Назначение onUnMask

Хук onUnMask используется в процессе извлечения «чистого» значения из поля ввода, на которое наложена маска. Его задача — вмешиваться в момент преобразования отображаемого пользователю значения (masked value) в внутреннее или передаваемое дальше значение (unmasked value).

Ключевая особенность заключается в том, что Inputmask разделяет два состояния данных:

  • маскированное значение — то, что отображается в input (с символами маски, разделителями, префиксами)
  • размаскированное значение — «чистые» данные без форматирования

onUnMask позволяет контролировать процесс перехода между этими состояниями.

Место onUnMask в жизненном цикле Inputmask

Внутренний поток обработки данных при извлечении значения выглядит упрощённо следующим образом:

  1. Пользователь вводит данные
  2. Inputmask применяет маску и форматирует отображение
  3. При запросе значения запускается процесс извлечения raw value
  4. Вызывается onUnMask
  5. Возвращается итоговое значение без маски

Важно понимать, что onUnMask не влияет на отображение ввода. Он срабатывает только в момент получения значения через API или внутренние механизмы библиотеки.

Сигнатура и параметры

Типичная сигнатура обработчика:

onUnMask: function (maskedValue, unmaskedValue) {
    return transformedValue;
}

Параметры:

  • maskedValue — текущее значение поля ввода с применённой маской
  • unmaskedValue — значение, уже очищенное от базовых символов маски
  • return value — итоговое значение, которое будет считаться «чистым»

Базовый пример использования

Inputmask({
  mask: "9999-9999",
  onUnMask: function (maskedValue, unmaskedValue) {
    return unmaskedValue;
  }
}).mask("#phone");

В данном случае onUnMask фактически не изменяет поведение, а лишь явно возвращает уже обработанное значение.

Модификация формата данных

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

Удаление нулей в начале

Inputmask({
  mask: "999999",
  onUnMask: function (maskedValue, unmaskedValue) {
    return unmaskedValue.replace(/^0+/, "");
  }
}).mask("#code");

Здесь происходит дополнительная обработка после стандартного удаления маски.

Приведение к числовому типу

Inputmask({
  mask: "999.999",
  onUnMask: function (maskedValue, unmaskedValue) {
    return Number(unmaskedValue);
  }
}).mask("#amount");

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

Взаимодействие с дробными и составными масками

При работе с разделителями (десятичные, телефонные форматы, даты) onUnMask часто используется для унификации данных.

Inputmask({
  mask: "99/99/9999",
  onUnMask: function (maskedValue, unmaskedValue) {
    const parts = unmaskedValue.split("/");
    return `${parts[2]}-${parts[1]}-${parts[0]}`;
  }
}).mask("#date");

В этом примере дата преобразуется из формата DD/MM/YYYY в YYYY-MM-DD.

Отличие onUnMask от других механизмов извлечения данных

Inputmask предоставляет несколько способов получения значения:

  • input.value — отображаемое значение с маской
  • getMaskedValue() — значение с форматированием
  • getUnmaskedValue() — очищенное значение
  • onUnMask — перехват и модификация процесса получения unmasked value

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

Особенности выполнения

1. Срабатывание только при извлечении значения

onUnMask не реагирует на ввод символов. Он активируется только при обращении к значению через API Inputmask или внутренние вызовы библиотеки.

2. Возможность полного переопределения результата

Возвращаемое значение полностью заменяет стандартный результат:

onUnMask: function (maskedValue, unmaskedValue) {
  return "fixed-value";
}

В этом случае независимо от ввода всегда будет возвращаться одно и то же значение.

3. Зависимость от конфигурации маски

Поведение unmaskedValue зависит от параметров маски:

  • removeMaskOnSubmit
  • autoUnmask
  • clearMaskOnLostFocus

onUnMask выполняется уже после базовой обработки этих опций.

Применение в реальных сценариях

Нормализация телефонных номеров

Inputmask({
  mask: "+7 (999) 999-99-99",
  onUnMask: function (maskedValue, unmaskedValue) {
    return unmaskedValue.replace(/\D/g, "");
  }
}).mask("#phone");

Результат всегда содержит только цифры, независимо от форматирования.

Подготовка данных для API

Inputmask({
  mask: "9999 9999 9999 9999",
  onUnMask: function (maskedValue, unmaskedValue) {
    return unmaskedValue.split(" ").join("");
  }
}).mask("#card");

Здесь удаляются пробелы, чтобы получить стандартный формат номера карты.

Условное преобразование

Inputmask({
  mask: "999-999",
  onUnMask: function (maskedValue, unmaskedValue) {
    if (unmaskedValue.startsWith("0")) {
      return null;
    }
    return unmaskedValue;
  }
}).mask("#serial");

Возможна реализация логики валидации прямо на этапе извлечения значения.

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

Избыточная логика преобразования

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

Игнорирование типа данных

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

return unmaskedValue + 1; // строковая конкатенация

Корректный вариант:

return Number(unmaskedValue) + 1;

Несогласованность форматов

При преобразовании даты или сложных структур важно сохранять единый формат на всём приложении. onUnMask не должен становиться единственным местом бизнес-логики преобразования.

Поведение при пустых значениях

Если поле пустое или содержит только символы маски, onUnMask может получить:

  • пустую строку
  • строку без значимых символов
  • частично заполненное значение

Рекомендуется явно обрабатывать такие случаи:

onUnMask: function (maskedValue, unmaskedValue) {
  if (!unmaskedValue) return "";
  return unmaskedValue;
}

Влияние на сериализацию данных

При отправке формы значение, возвращаемое onUnMask, становится финальным источником данных. Это означает, что сервер никогда не увидит исходную маску, только результат обработки.

Это делает onUnMask ключевым инструментом для:

  • унификации форматов
  • подготовки данных к API
  • удаления пользовательского форматирования
  • приведения типов

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

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

  • onBeforeMask — преобразование входных данных перед отображением
  • onBeforePaste — обработка вставляемого текста
  • oncomplete — реакция на завершение ввода
  • oncleared — обработка очистки поля

В этой цепочке onUnMask занимает финальную стадию извлечения данных.

Ограничения механизма

  • не предназначен для асинхронных операций
  • не влияет на DOM-значение напрямую
  • не предназначен для сложной бизнес-логики
  • работает только в рамках синхронного получения значения

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

Оглавление