Методы экземпляра

Экземпляр маски, создаваемый через Inputmask, представляет собой объект с набором методов, управляющих жизненным циклом маски, её состоянием, синхронизацией с DOM-элементом и взаимодействием с пользовательским вводом. Работа через экземплярный API обеспечивает более гибкий контроль по сравнению с декларативной инициализацией.

Инициализация и привязка к элементу

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

const im = new Inputmask({
  mask: "+7 (999) 999-99-99"
});

Однако сам по себе экземпляр не активен до момента привязки к элементу. Для этого используется метод mask().

mask()

Метод mask() выполняет основную операцию — подключает маску к DOM-элементу или коллекции элементов.

im.mask(document.querySelector("input"));

Допустимо передавать:

  • один DOM-элемент
  • NodeList
  • массив элементов

Повторный вызов mask() на уже замаскированном элементе не создаёт новый экземпляр, а использует существующую привязку.

Внутренне метод:

  • инициализирует состояние ввода
  • устанавливает обработчики событий (keydown, input, blur, focus)
  • нормализует начальное значение поля
  • синхронизирует буфер маски с DOM

remove()

Метод remove() отключает маску и восстанавливает исходное поведение элемента.

im.remove(document.querySelector("input"));

При удалении:

  • снимаются все event listeners
  • очищаются внутренние структуры данных маски
  • восстанавливается исходное значение input (если оно сохранялось)
  • элемент возвращается к стандартному HTML-вводу

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

setValue()

Метод setValue() позволяет программно установить значение с учётом правил маски.

im.setValue("+79991234567");

В отличие от прямого присваивания input.value, данный метод:

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

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

getValue()

Метод getValue() возвращает текущее значение поля.

const value = im.getValue();

Поведение метода зависит от конфигурации:

  • при включённой опции unmask возвращает «чистое» значение без маски
  • при стандартной конфигурации возвращает отформатированную строку
  • может учитывать состояние incomplete/complete маски

Типичная логика:

  • formatted value — отображаемое пользователю
  • unmasked value — данные для отправки на сервер

setOptions()

Метод setOptions() позволяет динамически изменять конфигурацию маски без её пересоздания.

im.setOptions({
  placeholder: "_",
  showMaskOnHover: false
});

После применения:

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

Особенно важно при адаптивных интерфейсах, где формат ввода зависит от состояния формы.

format()

Метод format() применяется для форматирования строки без привязки к DOM-элементу.

const formatted = im.format("79991234567");

Используется для:

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

Метод не изменяет состояние экземпляра и работает как чистая функция относительно текущей конфигурации.

unmaskedvalue()

Метод unmaskedvalue() возвращает значение без маски, независимо от настроек отображения.

const raw = im.unmaskedvalue();

Особенности:

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

Внутренне извлекает значения из буфера mask tokens, исключая литералы и placeholder-символы.

isComplete()

Метод isComplete() определяет, заполнена ли маска полностью.

if (im.isComplete()) {
  // значение соответствует полной маске
}

Возвращает:

  • true — если все обязательные позиции заполнены
  • false — если есть незаполненные обязательные символы

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

isValid()

Метод isValid() выполняет более строгую проверку, чем isComplete().

const valid = im.isValid();

Проверяет:

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

В некоторых конфигурациях может учитывать регулярные выражения или функции-валидаторы, встроенные в mask definition.

focus()

Метод focus() программно переводит фокус на элемент с маской.

im.focus();

Дополнительно:

  • устанавливает курсор в первую доступную позицию ввода
  • может учитывать опцию positionCaretOnClick
  • инициирует внутренние обработчики фокуса Inputmask

blur()

Метод blur() снимает фокус с элемента.

im.blur();

Используется для:

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

refreshValue()

Метод refreshValue() синхронизирует внутреннее состояние маски с текущим значением DOM-элемента.

im.refreshValue();

Применяется в случаях, когда значение input было изменено внешними скриптами без использования API Inputmask.

При вызове:

  • пересчитывается буфер маски
  • повторно применяется форматирование
  • обновляется caret position

detachEventHandlers() и reattachEventHandlers()

Низкоуровневые методы управления событиями.

im.detachEventHandlers();
im.reattachEventHandlers();

Используются редко и преимущественно внутри интеграций с фреймворками.

detachEventHandlers():

  • временно отключает обработчики ввода
  • предотвращает реакцию маски на изменения DOM

reattachEventHandlers():

  • восстанавливает обработчики
  • синхронизирует текущее состояние

getmetadata()

Метод getmetadata() возвращает метаданные текущей маски.

const meta = im.getmetadata();

Содержит:

  • описание маски
  • параметры генерации
  • вспомогательные настройки (в зависимости от конфигурации)

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

analyseMask()

Метод analyseMask() выполняет анализ текущего шаблона маски.

const analysis = im.analyseMask();

Результат может включать:

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

Метод полезен при отладке и построении динамических масок.

escape()

Метод escape() экранирует специальные символы маски.

const escaped = im.escape("+7 (999)");

Используется для:

  • безопасного формирования маски из пользовательского ввода
  • предотвращения интерпретации специальных символов как токенов
  • генерации динамических шаблонов

maskset access

Некоторые реализации предоставляют доступ к внутреннему maskset:

const set = im.maskset;

Это неформализованный API, позволяющий:

  • анализировать структуру маски
  • отлаживать поведение токенов
  • работать с raw-данными маскировки

Использование напрямую связано с внутренней архитектурой и требует понимания механизма tokenization.

value

Свойство value экземпляра отражает текущее значение маскированного поля.

console.log(im.value);

Поведение:

  • синхронизировано с DOM (но не всегда мгновенно)
  • зависит от режима обновления
  • может отличаться от getValue() в сложных сценариях

Управление состоянием экземпляра

Экземпляр Inputmask поддерживает внутреннее состояние, включающее:

  • текущую позицию курсора
  • буфер введённых символов
  • состояние completeness
  • режим редактирования

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

Оглавление