Создание плагинов

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

Ключевые точки расширения:

  • система definitions (определения символов маски)
  • механизм aliases (предустановленные шаблоны)
  • хук-функции обработки ввода
  • расширение поведения через Inputmask.extendDefinitions
  • модификация поведения через Inputmask.extendAliases
  • постобработка и препроцессинг значений
  • кастомные валидаторы и генераторы масок

Система definitions как основа плагинов

Каждый символ маски в Inputmask связан с объектом определения. Это определение описывает:

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

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

{
  validator: "[0-9]",
  cardinality: 1,
  definitionSymbol: "*"
}

Плагин, расширяющий поведение, чаще всего начинает с добавления нового символа в registry definitions. Этот механизм реализуется через глобальный объект Inputmask.

Расширение definitions через extendDefinitions

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

Расширение выполняется через:

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

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

Поведенческая модель расширения

После регистрации нового символа:

  1. символ распознаётся парсером маски
  2. применяется validator при каждом вводе
  3. учитывается cardinality при позиционировании курсора
  4. интегрируется в undo/redo стек

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

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

Validator может быть функцией, что превращает definition в полноценный модуль логики.

Inputmask.extendDefinitions({
  "H": {
    validator: function (ch) {
      return /[A-Fa-f0-9]/.test(ch);
    },
    cardinality: 1
  }
});

Функциональный валидатор позволяет реализовать:

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

Хуки обработки ввода

Плагины часто используют hook-механизмы, встроенные в Inputmask pipeline.

Основные точки вмешательства:

  • onBeforeMask
  • onBeforePaste
  • onUnMask
  • onBeforeWrite

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

Пример логики onBeforeMask

На стадии предварительного форматирования входное значение может быть нормализовано:

Inputmask.extendAliases({
  customAlias: {
    onBeforeMask: function (value) {
      return value.trim().toLowerCase();
    }
  }
});

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

Расширение aliases как форма плагинной архитектуры

Aliases представляют собой преднастроенные конфигурации масок. Каждый alias включает:

  • mask или pattern
  • definitions override
  • параметры поведения
  • набор хуков

Расширение aliases формирует уровень абстракции над definitions.

Inputmask.extendAliases({
  "phone-ext": {
    mask: "+7 (999) 999-99-99",
    greedy: false,
    clearIncomplete: true
  }
});

Aliases используются как инкапсуляция сложных масок, где plugin-поведение определяется не только символами, но и конфигурацией.

Композиция плагинов через цепочку расширений

Сложные плагины строятся как комбинация:

  1. extendDefinitions
  2. extendAliases
  3. хуки обработки
  4. post-processing логика

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

Постобработка значений как слой плагина

Post-processing применяется после завершения ввода или при извлечении значения из input.

Inputmask.extendAliases({
  numericCustom: {
    onUnMask: function (maskedValue) {
      return maskedValue.replace(/\s/g, "");
    }
  }
});

Этот слой используется для:

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

Динамические маски как расширение поведения

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

Механизм реализуется через функцию mask:

Inputmask.extendAliases({
  dynamicZip: {
    mask: function (opts) {
      return opts.numericInput ? "99999" : "99999-9999";
    }
  }
});

Здесь plugin-логика управляет структурой маски на лету, превращая Inputmask в реактивную систему форматирования.

Интеграция с пользовательскими data-атрибутами

Расширения часто используют HTML-метаданные для конфигурации поведения без изменения JavaScript-кода.

Пример модели:

  • data-inputmask
  • data-inputmask-alias
  • data-inputmask-mask

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

Расширение поведения курсора и позиционирования

Некоторые плагины изменяют алгоритм перемещения курсора. Это достигается через переопределение внутренних стратегий обработки позиции:

  • greedy mode
  • skipOptionalPartCharacter
  • placeholder behavior

Хотя прямой API ограничен, поведение может быть модифицировано через комбинацию definitions и hooks.

Безопасное расширение без конфликтов

При создании плагинов важна изоляция расширений. Основные принципы:

  • уникальные символы definitions
  • префиксирование alias-имён
  • отсутствие перезаписи базовых правил без необходимости
  • проверка существующих ключей перед расширением

Конфликтная ситуация возникает при перекрытии validator-логики одного символа несколькими плагинами, что приводит к неоднозначной валидации.

Переопределение и цепочки расширений

Механизм extend не заменяет существующие определения полностью, а расширяет или переопределяет их. Это создаёт цепочную модель:

  1. базовое определение
  2. расширение плагина A
  3. расширение плагина B
  4. итоговая конфигурация runtime

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

Инкапсуляция плагина через модульную структуру

Плагины обычно оформляются как независимые модули:

  • регистрация definitions при инициализации
  • регистрация aliases
  • подключение хуков
  • экспорт функции инициализации

Такая структура позволяет интегрировать расширения в сборщики (Webpack, Rollup, Vite) без изменения ядра библиотеки.

Расширенные сценарии плагинов

На практике плагины Inputmask реализуют:

  • маски валют с локализацией
  • динамические телефонные форматы
  • серийные номера с checksum-валидацией
  • структурированные идентификаторы (UUID-подобные)
  • контекстные маски на основе внешних данных

Каждый сценарий опирается на комбинацию definitions и runtime hooks, формируя специализированный слой над базовым движком маскирования.

Оглавление