onBeforeMask и onBeforePaste

Хук onBeforeMask в библиотеке Inputmask используется для предварительной обработки значения до применения маски. Этот механизм позволяет модифицировать исходные данные ещё до того, как движок начнёт сопоставлять их с шаблоном.

Основная идея заключается в том, что входное значение может приходить в «сыром» виде: с лишними символами, пробелами, нестандартным форматированием или даже в виде, частично совпадающем с маской. onBeforeMask предоставляет точку перехвата, где это значение можно нормализовать.

Сигнатура

onBeforeMask: function (value, opts) {
    return value;
}
  • value — исходная строка, которая будет подставлена в input или передана программно.
  • opts — объект конфигурации текущей маски, содержащий параметры, alias и дополнительные настройки.

Возвращаемое значение:

  • строка, которая будет дальше использоваться как входная для процесса маскирования;
  • при возврате undefined или null поведение зависит от версии, но обычно используется исходное значение без изменений.

Логика работы

Порядок обработки данных:

  1. Получение входного значения (инициализация, setValue, value property, динамическая установка).
  2. Вызов onBeforeMask.
  3. Применение алгоритма маски Inputmask.
  4. Построение финального отображаемого значения.

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

Типичные задачи

Нормализация входных данных

Часто данные приходят с внешних источников, где форматирование отличается:

Inputmask({
  mask: "+7 (999) 999-99-99",
  onBeforeMask: function (value) {
    return value.replace(/[^\d+]/g, "");
  }
}).mask(input);

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

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

Inputmask("99-99-9999", {
  onBeforeMask: function (value) {
    return value.replace(/\./g, "-");
  }
});

Если дата приходит в формате dd.mm.yyyy, она автоматически приводится к dd-mm-yyyy.

Предобработка телефонных номеров

onBeforeMask: function (value) {
  if (value.startsWith("8")) {
    return value.replace(/^8/, "+7");
  }
  return value;
}

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

Особенности поведения

  • Хук вызывается только до применения маски, а не при каждом вводе символа.
  • Не влияет на ввод пользователя в реальном времени напрямую, если значение уже прошло инициализацию.
  • Может использоваться совместно с динамическими alias, но выполняется раньше их логики форматирования.
  • Не предназначен для визуальных преобразований — только для подготовки данных.

Влияние на модель данных

Inputmask отделяет:

  • raw value (исходное значение)
  • buffered value (промежуточное состояние)
  • masked value (отображаемое значение)

onBeforeMask воздействует только на первый этап, изменяя raw value до попадания в буфер обработки.

onBeforePaste

Хук onBeforePaste применяется в момент вставки данных из буфера обмена. Он позволяет перехватить вставляемую строку и модифицировать её до того, как Inputmask начнёт её анализировать и применять маску.

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

Сигнатура

onBeforePaste: function (pastedValue, opts) {
    return pastedValue;
}
  • pastedValue — строка, вставленная пользователем.
  • opts — конфигурация маски и текущего инстанса Inputmask.

Возвращаемое значение:

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

Порядок обработки вставки

  1. Срабатывание события paste.
  2. Извлечение данных из clipboard.
  3. Вызов onBeforePaste.
  4. Очистка и подготовка значения Inputmask.
  5. Применение маски.
  6. Обновление input и внутренних буферов.

Практические сценарии

Удаление лишних символов из вставки

Inputmask({
  mask: "9999 9999 9999 9999",
  onBeforePaste: function (value) {
    return value.replace(/\s+/g, "");
  }
}).mask(input);

При вставке номера карты вида 1234 5678 9012 3456 пробелы удаляются до обработки.

Очистка HTML-формата

onBeforePaste: function (value) {
  return value.replace(/<[^>]*>/g, "");
}

Используется при копировании данных из HTML-источников, где могут попадать теги.

Унификация телефонных номеров при вставке

onBeforePaste: function (value) {
  return value
    .replace(/[^\d+]/g, "")
    .replace(/^8/, "+7");
}

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

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

  • Браузерная вставка (Ctrl+V) — хук срабатывает всегда.
  • Программная вставка через value assignment — обычно не вызывает onBeforePaste, используется onBeforeMask.
  • Drag & drop — поведение зависит от реализации браузера, но чаще трактуется как paste-событие.

Отличия от onBeforeMask

Несмотря на схожесть назначения, эти хуки работают в разных контекстах:

Хук Контекст Основная задача
onBeforeMask Инициализация и установка значения Подготовка исходных данных
onBeforePaste Вставка из буфера обмена Очистка вставляемых данных

Ключевое различие — источник данных: внешний программный ввод против пользовательской вставки.

Особенности обработки

  • Выполняется синхронно в момент paste-события.
  • Может полностью изменить вставляемую строку до обработки маской.
  • Не имеет доступа к DOM-событию напрямую (только значение).
  • Может использоваться для предотвращения некорректных форматов ещё до их попадания в input.

Комбинирование onBeforeMask и onBeforePaste

В сложных сценариях оба хука применяются совместно:

Inputmask({
  mask: "+7 (999) 999-99-99",

  onBeforeMask: function (value) {
    return value.replace(/[^\d+]/g, "");
  },

  onBeforePaste: function (value) {
    return value
      .replace(/\s/g, "")
      .replace(/^8/, "+7");
  }
}).mask(input);

В таком варианте:

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

Влияние на производительность и предсказуемость

Оба хука являются критическими точками перехвата данных. Неправильная логика в них может привести к:

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

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

Оглавление