Базовые паттерны

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

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

цифра
буква
алфавитно-цифровой символ
фиксированный литерал
пользовательское правило

Маска применяется к input-полю и начинает контролировать ввод в режиме реального времени.

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

Базовый набор символов Inputmask формирует фундамент большинства сценариев ввода.

Цифровые символы

9 — обязательная цифра

Символ 9 обозначает позицию, в которую допускается ввод только цифры (0–9). Символ является необязательным в том смысле, что поле может оставаться пустым, если не задано required.

Пример маски:

Поведение:

допустим ввод: 1234
недопустим ввод: 12a4

0 — обязательная цифра с принудительным заполнением

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

Пример:

Типичный сценарий — фиксированное количество разрядов, например PIN-коды.

Буквенные символы

a — буква (латиница и/или локализованные алфавиты)

Символ a допускает ввод только буквенных символов.

Пример:

aaaa

Допустимо:

test
AbCd

Недопустимо:

1234

Алфавитно-цифровые символы

*** — любой символ (буква или цифра)**

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

Пример:

****-****

Допустимо:

A1B2-C3D4
1234-ABCD

Литералы в маске

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

Пример:

+7 (999) 999-99-99

Здесь:

+, пробелы, скобки и дефисы — литералы
9 — динамические позиции

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

Экранные символы и placeholder

Каждая позиция маски может отображаться в виде placeholder — визуального индикатора ожидаемого типа данных.

Пример:

Mask: 9999-99-99
Placeholder: YYYY-MM-DD (визуально настраивается)

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

Поведение пустых значений

Базовые паттерны тесно связаны с обработкой пустых и частично заполненных значений.

Основные режимы:

showMaskOnHover — отображение маски при наведении
showMaskOnFocus — отображение маски при фокусе
clearIncomplete — очистка незавершённых значений

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

Квантификаторы повторения

Базовые паттерны поддерживают повторение символов через фигурные скобки.

Примеры:

9{4}

эквивалентно:

Диапазон повторений:

9{1,4}

означает от одной до четырёх цифр.

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

9{n}
a{n}
*{n}

Альтернативные и опциональные позиции

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

Символ ? используется для обозначения необязательной части маски:

(999) 999-9999[9]

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

9999?-9999

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

Сегменты и группировка

Для повышения читаемости маски используются логические группы.

Пример:

999-999-9999

или

(999) 999 9999

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

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

Базовые паттерны расширяются через механизм definitions, позволяющий переопределять или добавлять новые типы символов.

Пример:

Inputmask({
  mask: "hh:mm",
  definitions: {
    "h": {
      validator: "[0-2]",
      cardinality: 1
    }
  }
}).mask(input);

В этом случае символ h ограничивает ввод значениями 0–2.

Параметры определения:

validator — правило проверки (regex или функция)
cardinality — количество символов
casing — приведение к верхнему/нижнему регистру

Маски с фиксированной структурой

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

Примеры:

телефон:
```
+7 (999) 999-99-99
```
дата:
```
99/99/9999
```
индекс:
```
999999
```

Особенность таких масок — полное отсутствие опциональных сегментов.

Маски с частичной свободой ввода

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

Пример:

9999[-9999]

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

Маски с повторяющимися блоками

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

Пример:

(9999)*{1,3}

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

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

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

Смешанные паттерны

Базовые маски часто комбинируют разные типы символов:

aa-9999-***

Структура:

aa — буквенный префикс
9999 — числовой блок
*** — свободный блок

Такие комбинации позволяют описывать сложные форматы без написания кастомной логики.

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

При вставке (paste) Inputmask анализирует строку целиком и пытается сопоставить её с паттерном.

Алгоритм:

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

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

Маскирование и нормализация

Базовые паттерны работают в двух режимах:

маскированное значение — отображаемое пользователю
сырое значение — извлекаемое через API

Пример:

+7 (999) 123-45-67

Сырое значение:

79991234567

Это разделение критично для серверной обработки данных.

Граничные случаи базовых паттернов

Некоторые сценарии требуют учёта нестандартного поведения:

ввод только литералов без данных
частично заполненные маски
конфликты пользовательских definitions
пересечение масок в динамической смене паттерна

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

Приоритет символов в маске

При разборе паттерна используется строгий порядок интерпретации:

пользовательские definitions
стандартные символы (9, a, *)
литералы
опциональные сегменты
повторения

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