Свойства конфигурации

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

Базовые свойства маски

mask

Основной параметр, задающий структуру ввода.

  • Строка маски: "999-999-9999", "+7 (999) 999-99-99"
  • Символы-джокеры: 9 (цифра), a (буква), * (алфавитно-цифровой символ)

Фактически mask определяет шаблон, по которому Inputmask строит поведение каждого символа.

alias

Позволяет использовать предустановленные шаблоны.

  • "phone"
  • "datetime"
  • "email"
  • "decimal"

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

regex

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

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

Особенность: при regex-режиме поведение становится менее позиционно-строгим, но более гибким.

Отображение и визуальное поведение

placeholder

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

  • Статический вариант: "_", "•"
  • Полное отключение: ""

Placeholder влияет только на визуальный слой и не участвует в логике валидации.

showMaskOnFocus

Определяет, будет ли маска отображаться при фокусе на поле.

  • true — маска появляется при фокусе
  • false — маска скрыта до ввода

showMaskOnHover

Управляет отображением маски при наведении курсора.

Используется для UI, где важно минимизировать визуальный шум.

showMaskOnLeave

Определяет поведение поля при потере фокуса.

  • true — маска сохраняется
  • false — отображается только введённое значение

Управление логикой ввода

greedy

Контролирует «жадность» маски — заполнение необязательных частей.

  • true — маска занимает всю доступную длину
  • false — сокращается до фактического ввода

Особенно важно для динамических масок, где часть шаблона опциональна.

jitMasking

Just-in-time masking: маска применяется по мере ввода, а не заранее.

  • Уменьшает визуальную перегрузку
  • Ускоряет ввод в сложных масках

keepStatic

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

  • true — структура остаётся стабильной
  • false — Inputmask может перестраивать варианты маски

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

definitions

Кастомизация символов маски.

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

definitions: {
  '#': { validator: "[0-9]", cardinality: 1 },
  'X': { validator: "[A-Fa-f0-9]", cardinality: 1 }
}

Ключевое свойство для расширения системы масок без изменения базовой логики библиотеки.

Автоматическое поведение и очистка

autoUnmask

Определяет, в каком виде значение возвращается из input.

  • true — возвращается «чистое» значение без маски
  • false — возвращается отформатированное значение

Используется при интеграции с формами и API.

clearIncomplete

Очищает поле, если ввод не завершён.

  • true — незавершённые значения удаляются
  • false — сохраняются даже неполные данные

Критично для форм с обязательной валидацией.

nullable

Позволяет трактовать пустую маску как null.

  • true — пустое значение становится null
  • false — остаётся пустой строкой

Используется при строгой типизации данных.

clearMaskOnLostFocus

Очищает маску при потере фокуса, если ввод не завершён.

Отличается от showMaskOnLeave тем, что влияет на само значение, а не только на отображение.

Курсор и поведение редактирования

positionCaretOnClick

Определяет позицию курсора при клике.

  • "none" — фиксированная позиция
  • "lvp" — логика последнего валидного символа
  • "radixFocus" — фокус на разделителе (для чисел)

insertMode

Управляет режимом вставки символов.

  • true — вставка сдвигает остальные символы
  • false — замена символов

insertModeVisual

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

Позволяет отделить внутреннюю логику от отображения при редактировании.

shiftPositions

Разрешает сдвиг символов при редактировании.

Ключевое свойство для масок с динамическим заполнением.

Форматирование символов

casing

Принудительное изменение регистра вводимых символов.

  • "upper" — верхний регистр
  • "lower" — нижний регистр
  • "none" — без изменений

Применяется постфактум ко всем введённым символам.

inputmode

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

  • "text"
  • "numeric"
  • "decimal"
  • "tel"

Не влияет на логику Inputmask, но улучшает UX.

Обработка событий жизненного цикла

oncomplete

Срабатывает при полном заполнении маски.

Используется для автоматической отправки или перехода к следующему полю.

onincomplete

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

Позволяет реализовать мягкую валидацию.

oncleared

Срабатывает при полном очищении поля.

onBeforeMask

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

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

onBeforePaste

Обрабатывает значение из буфера обмена перед вставкой.

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

onBeforeWrite

Вызывается перед записью значения в input.

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

Пост-валидация и контроль состояния

postValidation

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

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

Пример сценария — проверка диапазонов дат или сложных кодов.

isComplete

Логическое свойство состояния маски.

Возвращает факт завершённости ввода в соответствии с шаблоном.

Управление поведением при вставке и редактировании

skipOptionalPartCharacter

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

Часто используется для ускоренного ввода в длинных шаблонах.

undo/redo поведение

Хотя не всегда явно конфигурируется, Inputmask учитывает историю изменений при включённых режимах редактирования, что зависит от комбинации insertMode, shiftPositions и greedy.

Совместное влияние параметров

Конфигурация Inputmask редко работает через отдельные свойства. Чаще всего поведение формируется комбинацией:

  • mask + definitions формируют структуру допустимых символов
  • greedy + keepStatic определяют динамичность шаблона
  • autoUnmask + clearIncomplete управляют финальным значением
  • insertMode + shiftPositions задают модель редактирования
  • onBeforePaste + onBeforeWrite формируют входной поток данных

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

Оглавление