Функция isValid

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

Внутренняя модель Inputmask разделяет процесс обработки ввода на несколько этапов: форматирование, маскирование, обновление буфера и валидацию. isValid относится к финальному уровню проверки, когда необходимо определить, соответствует ли текущее значение всем ограничениям маски.

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

  • фиксированный литерал
  • обязательный плейсхолдер (например, цифра)
  • опциональный символ
  • повторяемую группу
  • динамический алиас (например, дата, телефон, IP)

Сигнатура и варианты вызова

В зависимости от контекста использования Inputmask, функция isValid может вызываться как метод экземпляра маски или как часть статического API:

isValid(value: string, options?: Object): boolean

или через экземпляр:

inputmask.isValid()

Во втором варианте проверяется текущее значение, связанное с DOM-элементом.

Дополнительные параметры позволяют переопределять поведение проверки:

  • value — строка для проверки вне контекста input-элемента
  • options — конфигурация, влияющая на правила интерпретации (например, greedy, definitions, alias)

Внутренняя логика проверки

Алгоритм isValid можно разложить на несколько этапов:

1. Нормализация входного значения

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

  • маскирующих символов (если включён removeMaskOnSubmit)
  • placeholder-символов
  • пробелов и разделителей (в зависимости от конфигурации)

На этом этапе Inputmask приводит строку к внутреннему представлению, пригодному для сопоставления с шаблоном.

2. Разбор структуры маски

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

  • статические символы (-, /, .)
  • динамические определения (9 — цифра, a — буква, * — любой символ)
  • пользовательские definitions
  • группы и повторители

Каждый токен получает набор ограничений:

{ type: "numeric", required: true }
{ type: "literal", value: "-" }
{ type: "alpha", optional: true }

3. Поэлементное сопоставление

Строка проходит сравнение с маской слева направо. Для каждого символа выполняется проверка:

  • соответствует ли символ текущему токену
  • допустим ли пропуск (optional)
  • требуется ли backtracking при несовпадении

Особенно сложным является обработка повторяющихся сегментов, например:

(999) 999-9999

или динамических масок:

aa[-999]

4. Проверка полноты заполнения

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

  • незаполненные required поля → invalid
  • частично заполненные группы → invalid
  • наличие placeholder-символов → invalid (в строгом режиме)

Поведение при различных конфигурациях

greedy режим

При greedy: true маска стремится захватить максимальное количество символов. Это влияет на isValid, так как проверка учитывает максимально возможное развертывание маски.

autoUnmask

Если включён autoUnmask, значение может быть преобразовано в «чистый» вид перед проверкой, что изменяет результат:

  • "123-45" может считаться валидным в masked режиме
  • но невалидным в unmasked контексте

definitions

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

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

В этом случае isValid учитывает кастомные правила, расширяя стандартный набор токенов.

Примеры поведения

Проверка телефонного номера

Маска:

Inputmask("(999) 999-9999");

Проверка:

  • (123) 456-7890 → true
  • (123) 45_-7890 → false
  • (12) 345-67890 → false

Причина отказа в последнем случае — несоответствие структуре сегментов и нарушенная группировка.

Проверка даты

Маска:

Inputmask("99/99/9999");
  • 12/08/2025 → true
  • 12/8/2025 → false (нарушение фиксированной длины сегмента)
  • 12/08/20_5 → false (наличие незаполненного символа)

Альтернативные маски

Inputmask({
  mask: ["99-99", "999-999"]
});

Значение считается валидным, если полностью соответствует одной из альтернативных структур. isValid выполняет проверку по всем вариантам и возвращает true, если хотя бы одна ветка проходит полностью.

Частичные значения и строгая валидация

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

Состояние Описание
partial структура допустима, но не заполнена
complete полностью соответствует маске
invalid нарушена структура или тип

isValid ориентируется именно на состояние complete. Это означает, что частично заполненные значения почти всегда дают false.

Влияние placeholder

Placeholder символы (_ по умолчанию) не считаются допустимыми значениями. При проверке:

  • если placeholder остался → значение невалидно
  • если placeholder удалён и сегмент заполнен → валидно

Это важно при использовании кастомных placeholder-символов:

Inputmask("999-999", { placeholder: " " });

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

Сравнение с другими методами валидации

isValid отличается от:

  • isComplete — проверяет только завершённость ввода
  • isMaskedValue — определяет, применена ли маска
  • HTML5 validation (pattern, type) — не учитывает структуру маски

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

Типичные ошибки использования

Проверка «сырого» значения без маски

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

Игнорирование альтернативных масок

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

Конфликт кастомных definitions

Переопределение стандартных символов (9, a, *) без учёта cardinality может нарушить логику isValid.

Особенности работы с динамическими алиасами

При использовании алиасов (datetime, numeric, email) проверка переходит от статической маски к специализированным валидаторам. В этом режиме:

  • структура маски может изменяться во время ввода
  • isValid учитывает внутренние парсеры алиаса
  • возможны дополнительные ограничения (например, диапазоны дат)

Пример:

Inputmask("datetime", {
  inputFormat: "dd/mm/yyyy"
});

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

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

Алгоритм isValid имеет линейную сложность относительно длины строки, но может усложняться при:

  • использовании альтернативных масок
  • глубокой вложенности definitions
  • активных алиасах с валидацией логики (например, даты)

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

Оглавление