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

При использовании Inputmask ключевая особенность заключается в том, что значение поля ввода существует в двух представлениях: сырое (unmasked) и отформатированное (masked). При ручном вводе преобразование происходит по событиям input/keydown, однако при программной установке значения поведение зависит от того, через какой механизм и в каком состоянии маска применяется к элементу.

Основная сложность заключается в том, что простое присваивание value не всегда приводит к корректному применению маски, особенно если маска уже инициализирована или если значение устанавливается до завершения привязки Inputmask.

Внутренний принцип преобразования значения

После инициализации Inputmask перехватывает ввод и преобразует его по следующим правилам:

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

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

Прямое присваивание value

const input = document.querySelector("input");
input.value = "79991234567";

Такой способ:

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

После инициализации маски:

Inputmask("+7 (999) 999-99-99").mask(input);
input.value = "79991234567";

В этом случае результат зависит от момента выполнения: если Inputmask уже активен, он может не переработать значение автоматически.

Рекомендуемый механизм setValue

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

const im = Inputmask("+7 (999) 999-99-99").mask(input);
im.setValue("79991234567");

или через jQuery-интерфейс:

$(input).inputmask("setvalue", "79991234567");

Этот механизм отличается тем, что:

  • вызывает внутренний pipeline форматирования
  • учитывает alias и pre-processing
  • синхронизирует masked и unmasked состояния
  • корректно обновляет буфер маски

Форматирование при программной установке

При вызове setValue значение проходит через цепочку обработки:

  1. onBeforeMask — предварительная нормализация входа
  2. применение alias (например, phone, datetime, numeric)
  3. построение masked-строки
  4. запись в input.value
  5. синхронизация internal buffer

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

Хуки, влияющие на результат форматирования

onBeforeMask

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

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

В контексте программной установки это означает, что любое значение, переданное через setValue, также будет нормализовано.

onBeforeWrite

Срабатывает при записи значения в input и позволяет модифицировать итоговый вывод:

onBeforeWrite: function (event, buffer, caretPos, opts) {
  return {
    refreshFromBuffer: true,
    buffer: buffer
  };
}

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

Разница между masked и unmasked установкой

Inputmask поддерживает два способа задания значения:

masked value

input.inputmask.setValue("+7 (999) 123-45-67");

Значение интерпретируется как уже отформатированное и вставляется напрямую в buffer.

unmasked value

input.inputmask.setValue("79991234567");

В этом случае значение проходит полное форматирование.

autoUnmask и влияние на программную установку

Параметр autoUnmask изменяет поведение получения и установки значения:

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

При активном autoUnmask:

  • value может возвращать чистое значение
  • setValue чаще работает в режиме raw input
  • возможны расхождения между DOM и внутренним состоянием

Особенности работы в динамических фреймворках

При использовании React, Vue или Angular возникают дополнительные нюансы:

React

  • прямое изменение value через state может конфликтовать с Inputmask
  • требуется синхронизация через ref и imperative API

Vue

  • v-model может перезаписывать отформатированное значение
  • Inputmask должен применяться после mount и после обновлений DOM

Angular

  • ngModel обновляет значение асинхронно
  • Inputmask может «переигрывать» формат при change detection

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

При многократном вызове setValue:

  • Inputmask пересчитывает buffer заново
  • caret position сбрасывается или пересчитывается
  • возможна потеря промежуточного форматирования при нестабильной маске

Особенно это заметно при масках с динамическими токенами (*, [9], {+}).

Влияние deferred и lazy режимов

При использовании опций:

  • lazy: true
  • showMaskOnHover
  • showMaskOnFocus

программная установка значения может приводить к тому, что:

  • часть маски не отображается до фокуса
  • значение выглядит «неполным» до активации input
  • buffer существует, но не визуализирован полностью

Форматирование числовых и датированных значений

Для alias numeric и datetime форматирование при установке особенно чувствительно к локали и конфигурации:

Inputmask({
  alias: "numeric",
  groupSeparator: " ",
  autoGroup: true
}).mask(input);

input.inputmask.setValue("1000000");

Результат:

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

Для datetime:

Inputmask({
  alias: "datetime",
  inputFormat: "dd.mm.yyyy"
}).mask(input);

input.inputmask.setValue("20260520");

Значение проходит через парсер даты и приводится к заданному формату.

Синхронизация internal buffer и DOM

Ключевой момент при программной установке — расхождение между:

  • input.value
  • input.inputmask._valueSet
  • internal buffer array

Метод setValue гарантирует синхронизацию всех трёх уровней. При прямом присваивании value синхронизация не выполняется автоматически, что приводит к рассинхронизации поведения маски при следующем вводе.

Пересчёт курсора при установке

После setValue Inputmask:

  • пересчитывает caret position
  • нормализует позиции символов
  • учитывает skip-literals настройки

При сложных масках курсор может быть установлен в первую свободную позицию или в конец заполненной части в зависимости от конфигурации greedy и autoUnmask.

Программная установка в режиме partial input

Если маска допускает неполные значения:

Inputmask({
  mask: "9999-9999",
  showMaskOnFocus: true
}).mask(input);

input.inputmask.setValue("123");

Результат:

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

Обработка ошибок форматирования при установке

Некорректные входные значения при setValue не вызывают исключения, но приводят к:

  • частичному заполнению маски
  • отбрасыванию неподходящих символов
  • нормализации по правилам mask definition

Например, при numeric маске:

input.inputmask.setValue("12ab34");

буквенные символы будут проигнорированы, если не настроены дополнительные правила обработки.

Итоговая модель поведения программного форматирования

Поведение Inputmask при программной установке значения определяется сочетанием трёх факторов:

  • способ установки (value, setValue, jQuery API)
  • конфигурация маски (alias, options, hooks)
  • текущее состояние инициализации input

Корректная работа форматирования достигается только при использовании внутреннего API, который запускает полный цикл преобразования значения через mask engine, buffer и hooks без обхода промежуточных этапов.

Оглавление