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

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

Наиболее часто используемые стандартные токены:

  • 9 — любая цифра (0–9)
  • a — буква латинского алфавита (A–Z, a–z)
  • ***** — буквенно-цифровой символ (буквы и цифры)

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

Механизм definitions в Inputmask

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

Каждый символ в маске соответствует записи вида:

  • validator — функция проверки символа
  • cardinality — количество занимаемых позиций
  • prevalidator — предварительные проверки (опционально)
  • casing — преобразование регистра (опционально)

Структура definitions упрощённо:

{
  "9": {
    validator: "[0-9]",
    cardinality: 1
  },
  "a": {
    validator: "[A-Za-z]",
    cardinality: 1
  },
  "*": {
    validator: "[A-Za-z0-9]",
    cardinality: 1
  }
}

При обработке ввода Inputmask проходит по маске слева направо, сопоставляя каждый символ с соответствующим правилом из definitions.

Переопределение стандартных символов через extendDefinitions

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

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

Inputmask.extendDefinitions({
  "9": {
    validator: "[0-9-]",
    cardinality: 1
  }
});

В данном случае стандартный символ 9 перестаёт ограничиваться только цифрами и начинает принимать также дефис.

Особенности поведения при расширении

  • Переопределение затрагивает все маски, использующие данный символ
  • Изменения применяются глобально
  • Поведение может конфликтовать с уже существующими масками
  • Приоритет отдаётся последнему определению

Локальное переопределение definitions в конкретной маске

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

Inputmask({
  mask: "999-999",
  definitions: {
    "9": {
      validator: "[0-9-]",
      cardinality: 1
    }
  }
}).mask(input);

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

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

При обработке ввода учитывается несколько уровней приоритета:

  1. Локальные definitions (переданные в конфигурации маски)
  2. Глобальные definitions (из extendDefinitions)
  3. Встроенные определения библиотеки

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

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

Стандартные токены можно полностью заменить, изменив их семантику.

Пример изменения поведения a

Inputmask.extendDefinitions({
  "a": {
    validator: "[А-Яа-яЁё]",
    cardinality: 1
  }
});

Теперь символ a принимает кириллицу вместо латиницы.

Пример замены * на строгое правило

Inputmask.extendDefinitions({
  "*": {
    validator: "[A-F0-9]",
    cardinality: 1
  }
});

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

Добавление новых символов маски

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

Inputmask.extendDefinitions({
  "#": {
    validator: "[1-5]",
    cardinality: 1
  }
});

Теперь символ # может использоваться в маске:

Inputmask("##-##").mask(input);

Использование функций-валидаторов

Validator не ограничивается регулярными выражениями. Допускается использование функции:

Inputmask.extendDefinitions({
  "9": {
    validator: function (ch) {
      return ch >= "0" && ch <= "9";
    },
    cardinality: 1
  }
});

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

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

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

Inputmask.extendDefinitions({
  "a": {
    validator: "[A-Za-z]",
    cardinality: 1,
    casing: "upper"
  }
});

Возможные значения:

  • upper — преобразование в верхний регистр
  • lower — преобразование в нижний регистр

Переопределение с использованием prevalidator

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

Inputmask.extendDefinitions({
  "9": {
    validator: "[0-9]",
    cardinality: 1,
    prevalidator: [
      {
        validator: "[0-9]",
        cardinality: 1
      }
    ]
  }
});

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

Типичные сценарии переопределения

Телефонные маски с расширенными символами

Inputmask.extendDefinitions({
  "9": {
    validator: "[0-9\\s\\-]",
    cardinality: 1
  }
});

Позволяет вводить пробелы и дефисы в числовых полях.

Маска серийного кода

Inputmask.extendDefinitions({
  "S": {
    validator: "[A-Z0-9]",
    cardinality: 1,
    casing: "upper"
  }
});

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

Inputmask("SSSS-SSSS").mask(input);

Ограничение на шестнадцатеричные символы

Inputmask.extendDefinitions({
  "h": {
    validator: "[0-9A-Fa-f]",
    cardinality: 1,
    casing: "upper"
  }
});

Конфликты и перекрытие символов

Переопределение стандартных символов может приводить к конфликтам:

  • маски, ожидающие стандартное поведение 9, начинают принимать расширенный набор символов
  • сторонние компоненты, зависящие от стандартной логики, могут работать некорректно
  • глобальные изменения влияют на все экземпляры Inputmask

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

Поведение при частичном вводе

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

Если validator слишком строгий, возможны эффекты:

  • блокировка ввода до завершения шаблона
  • невозможность вставки значений
  • некорректная работа backspace и paste

Совместимость с другими настройками маски

Переопределённые символы взаимодействуют с:

  • greedy режимом
  • clearIncomplete
  • autoUnmask
  • skipOptionalPartCharacter

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

Стратегии безопасного переопределения

Использование переопределения требует контроля области действия:

  • локальные definitions для отдельных масок
  • избегание изменения 9, a, * на глобальном уровне без необходимости
  • создание новых символов вместо модификации стандартных
  • изоляция сложных правил в отдельные токены

Такой подход снижает вероятность непредсказуемого поведения при масштабировании интерфейса ввода.

Оглавление