IMask: маски ввода и 6 интерактивных примеров
Телефон, расчёт суммы, даты, HEX/RGB, артикул и пакетное форматирование. Попробуйте IMask прямо на странице, сравните значения и скачайте готовый код.
Пользователь вставляет телефон с пробелами, вводит цену через точку или пытается указать 31 февраля. Поле может выглядеть аккуратно и при этом содержать данные, которые нельзя использовать. Хорошая форма должна помогать вводу, объяснять состояние и отдельно проверять смысл результата.
IMask поддерживает шаблонные, числовые, календарные и динамические маски, а также форматирование без привязки к полю через pipe. Библиотека разделяет отображаемое, очищенное и типизированное значения, как описано в официальном руководстве. Ниже мы проверим эти возможности на шести собственных интерфейсах, а не только на отдельных инпутах.
Что будем проверять
В каждом примере ввод связан с конкретным результатом. Из телефона получается учебный запрос, из цены и количества сумма, из двух дат период, из цвета оформление карточки, из артикула результат каталога. В пакетной обработке отдельно видны принятые и отклонённые строки.
- Телефон: форматирование, незаполненное состояние и данные для запроса.
- Цена: разделители, точность, ноль, пустое поле и расчёт.
- Даты: существование даты, допустимый диапазон и порядок границ.
- HEX/RGB: динамический выбор маски и акцент интерфейса.
- Артикул: верхний регистр, полный шаблон и поиск в каталоге.
- Пакет: строгая проверка строк до форматирования и экспорт результата.
Живая мастерская IMask
Введите своё значение, вставьте строку или используйте кнопки примеров. Рядом отображаются value, unmaskedValue и typedValue. В шаблонных сценах можно скрывать незаполненную часть и менять режим замены символов. «Развернуть» увеличивает мастерскую до размеров окна, Escape возвращает встроенный режим без перезагрузки.
Используйте учебные данные. Здесь нет звонков, SMS, платежей или отправки формы: действия работают только в текущей вкладке. Скачанный JSON содержит введённые значения, поэтому не публикуйте его, если экспериментировали с личной информацией.
Шесть прикладных сценариев
Телефон: заполненный шаблон и готовность запроса
Вставьте 79000000000: поле покажет телефон с разделителями. При ручном наборе вводите десять цифр после уже заданного +7, не повторяя код страны. Затем попробуйте короткую строку 7900123. Кнопка подготовки запроса станет недоступной, а интерфейс объяснит, что номер не готов. После заполнения «Собрать учебный запрос» покажет локальный JSON без отправки.
Мы используем шаблон +{7} (000) 000-00-00. Фигурные скобки включают фиксированную семёрку в unmaskedValue, поэтому в raw-строке сохраняется код, но не пробелы и скобки; такое поведение описано в разделе Pattern Mask. При подготовке запроса приложение отдельно добавляет знак плюса.
Это пример одного формата, а не международный телефонный валидатор. Полностью заполненная маска не доказывает, что номер существует или принадлежит пользователю. В рабочей форме эти вопросы решаются отдельно от форматирования.
Проверить телефон и raw-значение
Сумма: использовать число, а не строку с пробелами
Введите 1250.50, измените количество и сравните три представления значения. В поле отображается цена с разделителем тысяч, raw-строка не содержит пробел, а typedValue является числом. Расчёт ниже использует именно число.
Числовая маска настраивается через scale, radix, mapToRadix, thousandsSeparator и границы диапазона, согласно описанию Number Mask. В нашем примере разрешены значения от 0 до 100000, а точка принимается как десятичный разделитель и отображается запятой.
Попробуйте ноль и полностью пустое поле: это разные состояния. Нулевая цена даёт нулевую сумму, пустое поле не запускает расчёт. Количество должно быть целым от 1 до 99. Переключите режим «Только целые» и проверьте, что произошло с дробной частью, прежде чем использовать результат.
Все цены вымышленные. Умножение выполняется через целое количество копеек, но это не платёжная система и не расчёт налогов. Маска отвечает за ввод числа, а правила вычисления остаются частью приложения.
Период: реальная дата ещё не гарантирует правильный диапазон
Начальный пример охватывает период с 28 февраля по 1 марта 2028 года. Обе границы включены, поэтому получается три календарных дня. Введите 29 февраля, затем попробуйте 31 февраля и посмотрите, какое значение действительно осталось в поле.
Календарная маска проверяет дату после заполнения: промежуточное состояние может ещё содержать невозможную комбинацию дня и месяца, а последняя цифра не будет принята. Это ограничение прямо описано в разделе Date Mask. В мастерской мы не называем такой ввод готовым периодом.
Затем задайте окончание раньше начала. Обе даты могут быть корректными, но приложение отклонит их порядок. Допустимый диапазон в этом примере фиксирован: с 1 января 2026 года по 31 декабря 2030 года; это учебное ограничение, а не текущая доступность бронирования.
В JSON даты сохраняются как локальные календарные строки YYYY-MM-DD, без преобразования в UTC-момент. Количество дней рассчитывается по календарным компонентам, без предположения о длительности местных суток. Здесь нет времени суток, дат поездок или реального бронирования.
Проверить даты и порядок границ
Динамическая маска: HEX и RGB в одном поле
Попробуйте #155959, затем 255,128,064. Мастерская переключит формат и обновит цветовой образец, границу кнопки и CSS-переменную. Для однозначного RGB-ввода используйте по три цифры на компонент, например 021,089,089.
Динамическая маска задаётся массивом вариантов, а функция dispatch позволяет выбирать вариант явно; обе возможности описаны в разделе Dynamic Mask. Здесь символ # выбирает HEX, остальное вводится как три RGB-компонента в диапазоне 0–255.
Удалите часть HEX-кода. Поле останется доступным для продолжения ввода, но приложение не примет неполный цвет и сохранит последний корректный предпросмотр. Это специально показывает разницу между допустимым промежуточным состоянием и готовым значением.
«Копировать CSS» сохраняет переменную акцентного цвета. Контраст текста автоматически не гарантируется: выбрав светлый цвет, вы сами увидите, что его нельзя без проверки использовать для текста на светлом фоне.
Артикул: маска, нормализация и реальный результат поиска
Введите sku-fm-0017: буквы преобразуются в верхний регистр, а результат покажет учебную форму заявки. Затем введите SKU-ZZ-9999. Шаблон заполнен, но записи нет, поэтому мастерская не предложит добавить её в заявку.
Для двух букв используются собственные definitions, а prepareChar преобразует ввод в верхний регистр, как описано в руководстве по шаблонам и подготовке символов. Поиск выполняется отдельно по трём учебным записям. Маска не знает содержимого каталога.
Кнопки под полем позволяют проверить все существующие коды без запоминания. Такой интерфейс подходит для внутренних идентификаторов с заранее известным форматом. Он не подходит для произвольных названий, где жёсткая маска мешала бы вводу.
Пакетная обработка: не исправлять ошибки молча
Вставьте суммы по одной на строку и нажмите «Проверить и форматировать». Корректные строки получат единое представление, а буквы, неверные разделители и значения вне диапазона останутся ошибками. Например, abc не превратится в ноль, а 12,3,4 не станет другим числом.
IMask предоставляет pipe и createPipe для форматирования без поля ввода, а типы источника и результата задаются через PIPE_TYPE, согласно разделу Pipe. В нашем примере до вызова библиотеки выполняется отдельная строгая проверка исходной строки.
Ограничения мастерской: до 50 строк и 10 000 байт, диапазон 0–100000, максимум две цифры после десятичного разделителя. Пустые строки пропускаются. Если изменить текст после обработки, экспорт отключится до следующего запуска, чтобы не скачать устаревший результат по ошибке.
JSON содержит все непустые строки, включая отклонённые и причины отказа. Это удобнее для разбора ошибок, чем молча выбросить часть данных. Пример не предназначен для больших таблиц и не заменяет полноценный импорт с собственной схемой.
Три значения и две разные проверки
value представляет строку маски, unmaskedValue даёт строковое значение без части форматирования, а для Number и Date можно использовать типизированное typedValue. Фиксированные части могут сохраняться в raw-значении в зависимости от шаблона, поэтому не стоит считать его автоматически «только цифрами»; это следует из описания значений и Pattern Mask.
Завершённость маски и готовность данных для действия не равны. В мастерской отдельно проверяются пустая цена, порядок дат, полный HEX-код и наличие артикула в каталоге. Событие complete имеет смысл прежде всего для шаблонных масок, что отмечено в руководстве по событиям.
Не делайте поле непреодолимой преградой. Пользователь должен иметь возможность удалить значение, вставить строку, переместить курсор и понять, почему результат пока не готов. Серверная проверка остаётся необходимой в настоящем приложении независимо от поведения браузера.
Подключение и готовый код
В мастерской закреплена IMask 7.6.1. Установка: npm install imask@7.6.1. Для маски используйте input type="text", а подходящую экранную клавиатуру подсказывайте через inputmode; требование к типу поля приведено в Getting Started.
<label for="price">Учебная цена</label>
<input id="price" type="text" inputmode="decimal">
<output id="result"></output>import IMask from 'imask';
const price = IMask(document.querySelector('#price'), {
mask: Number,
min: 0,
max: 100000,
scale: 2,
thousandsSeparator: ' ',
radix: ',',
mapToRadix: ['.'],
padFractionalZeros: true
});
price.on('accept', () => {
const empty = price.unmaskedValue === '';
document.querySelector('#result').textContent = empty
? 'Введите цену'
: `Число для расчёта: ${price.typedValue}`;
});
// При удалении поля из интерфейса:
// price.destroy();Под каждой сценой находится настройка именно её маски с текущими параметрами. Это ядро подключения, не весь интерфейс. Полный ZIP включает JavaScript, CSS, учебные данные, предметные проверки, связанные результаты, экспорт и README с командами запуска.
Настройки существующей маски можно менять через updateOptions, но менять её тип таким способом нельзя; экземпляр уничтожается через destroy, согласно описанию жизненного цикла. При переходе между разными сценами наша мастерская создаёт новые экземпляры, а настройки шаблона меняет без замены поля.
Что проверить перед внедрением
- Промежуточные состояния: пустое поле, одна цифра, незаконченная дата, удаление в середине и вставка текста. Маска должна позволять дойти до правильного результата.
- Предметные правила: существование записи, допустимость диапазона и право пользователя на действие. Формат не доказывает достоверность данных.
- Нормализация: покажите, что изменилось при вставке, округлении или смене точности. Не выдавайте молча преобразованное значение за исходное.
- Доступность: оставьте подписи, объяснение формата, состояние ошибки и видимый фокус. Незаполненный шаблон не должен быть единственной инструкцией.
- Сохранение: заранее определите, что ожидает API: строку, число, код с префиксом или календарную дату. Не отправляйте отображаемый текст просто потому, что он красиво выглядит.
Сначала выберите сцену, близкую к вашей форме, и попробуйте неудобные варианты ввода. Польза IMask здесь не в подчёркиваниях и скобках, а в том, что человеку проще ввести данные и увидеть, готовы ли они к следующему действию.
