Кастомные обработчики событий

Библиотека Inputmask реализует событийную модель, в которой взаимодействие с полем ввода сопровождается как стандартными DOM-событиями, так и внутренними callback-хуками. Такой подход позволяет перехватывать изменения маски, отслеживать состояние ввода и внедрять дополнительную бизнес-логику без модификации ядра библиотеки.

Событийная система Inputmask условно делится на два уровня:

  • обработка через параметры конфигурации маски (callback-функции);
  • обработка через нативные DOM-события и пользовательские события, генерируемые библиотекой.

Callback-обработчики как основа событийной модели

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

oncomplete

Срабатывает при полном заполнении маски, когда введённое значение соответствует заданному шаблону.

Inputmask({
  mask: "+7 (999) 999-99-99",
  oncomplete: function () {
    console.log("Маска полностью заполнена");
  }
}).mask("#phone");

Состояние считается завершённым только при валидном заполнении всех обязательных сегментов. Переход курсора и наличие placeholder-символов учитываются при вычислении статуса.

onunmask / onincomplete

Callback onincomplete вызывается при потере фокуса или явной проверке состояния, если маска не заполнена полностью.

Inputmask({
  mask: "9999-9999",
  onincomplete: function () {
    console.log("Ввод не завершён");
  }
}).mask("#code");

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

oncleared

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

Inputmask({
  mask: "999-999",
  oncleared: function () {
    console.log("Поле очищено");
  }
}).mask("#serial");

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

onKeyValidation

Используется для перехвата каждого символа до его применения к маске. Позволяет реализовывать дополнительную валидацию на уровне клавиатурного ввода.

Inputmask({
  mask: "9999",
  onKeyValidation: function (key, result) {
    console.log("Клавиша:", key, "Результат:", result);
  }
}).mask("#pin");

Параметр result содержит информацию о том, был ли символ принят маской, отклонён или преобразован.

Привязка к нативным DOM-событиям

Несмотря на наличие встроенных callback-ов, Inputmask полностью интегрируется с DOM-уровнем событий браузера. Это позволяет использовать стандартные механизмы:

  • input
  • keydown
  • keypress
  • blur
  • focus
  • paste

Пример комбинированной обработки

const element = document.querySelector("#phone");

Inputmask("+7 (999) 999-99-99").mask(element);

element.addEventListener("input", function (e) {
  console.log("DOM input:", e.target.value);
});

В таком режиме Inputmask модифицирует значение поля до того, как событие input становится доступным для обработчиков, что позволяет получать уже отмаскированное значение.

Пользовательские события Inputmask

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

complete

Аналог callback oncomplete, но в виде DOM-события.

element.addEventListener("complete", function () {
  console.log("Маска завершена (event)");
});

incomplete

Фиксирует незавершённое состояние поля при потере фокуса.

element.addEventListener("incomplete", function () {
  console.log("Маска не заполнена");
});

clearmask / setvalue

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

element.addEventListener("clearmask", function () {
  console.log("Маска очищена программно");
});

Перехват событий при программном изменении значения

Inputmask изменяет значение поля не только через пользовательский ввод, но и через API:

const im = new Inputmask("999-999");
im.mask("#code");

document.querySelector("#code").value = "123456";

Для отслеживания таких изменений используется механизм синтетических событий, которые могут не всегда совпадать с нативными input или change.

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

  • наблюдение через MutationObserver;
  • перехват через callback onBeforeWrite;
  • использование setvalue-событий при их наличии.

onBeforeWrite как низкоуровневый перехват

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

Inputmask({
  mask: "9999-9999",
  onBeforeWrite: function (event, buffer, caretPos, opts) {
    return {
      refreshFromBuffer: true,
      buffer: buffer
    };
  }
}).mask("#field");

Этот уровень контроля используется для:

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

Совмещение нескольких обработчиков

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

Inputmask({
  mask: "9999 9999 9999 9999",
  oncomplete: function () {
    console.log("Карточный номер введён");
  },
  oncleared: function () {
    console.log("Карточный номер очищен");
  }
}).mask("#card");

const card = document.querySelector("#card");

card.addEventListener("blur", function () {
  console.log("Blur обработан на уровне DOM");
});

Такое разделение позволяет:

  • отделять бизнес-логику от низкоуровневой обработки;
  • комбинировать внутренние и внешние события;
  • управлять потоком данных без модификации ядра Inputmask.

Особенности порядка вызова событий

При взаимодействии с Inputmask важно учитывать последовательность:

  1. Нативное событие клавиатуры (keydown, keypress)
  2. Обработка символа внутри Inputmask
  3. Обновление буфера маски
  4. Запись значения в DOM
  5. Генерация input
  6. Вызов callback-функций (onKeyValidation, oncomplete, onincomplete)
  7. Генерация пользовательских событий (complete, incomplete)

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

Обработка событий при вставке (paste)

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

Inputmask({
  mask: "9999-9999",
  onBeforePaste: function (pastedValue, opts) {
    return pastedValue.replace(/\D/g, "");
  }
}).mask("#code");

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

  • перерасчёт маски;
  • обновление буфера;
  • срабатывание oncomplete или onincomplete.

Синхронизация с внешними состояниями

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

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

  • input для синхронизации значения;
  • oncomplete для фиксации валидного состояния;
  • oncleared для сброса состояния модели.

Управление жизненным циклом обработчиков

Обработчики Inputmask могут быть динамически изменены или удалены через повторную инициализацию маски:

const el = document.querySelector("#phone");

const im = new Inputmask({
  mask: "999-999",
  oncomplete: function () {
    console.log("complete v1");
  }
}).mask(el);

// переинициализация с новым обработчиком
im.remove();

Inputmask({
  mask: "999-999",
  oncomplete: function () {
    console.log("complete v2");
  }
}).mask(el);

Такой подход используется при изменении конфигурации маски в runtime-сценариях.

Обработка ошибок и нестандартных состояний

Хотя Inputmask не реализует полноценную систему исключений, обработка нестандартных ситуаций возможна через комбинацию событий:

  • некорректный ввод фиксируется через onKeyValidation;
  • незавершённые состояния через onincomplete;
  • очищение через oncleared.

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

Оглавление