Создание собственных алиасов

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

Пользовательские алиасы особенно полезны в следующих ситуациях:

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

Базовое применение выглядит следующим образом:

Inputmask.extendAliases({
    articleCode: {
        mask: "AAA-9999",
        placeholder: "_"
    }
});

Inputmask("articleCode").mask("#product");

После регистрации алиаса "articleCode" он становится полноценным встроенным типом маски.

Метод extendAliases

Создание пользовательских алиасов выполняется через:

Inputmask.extendAliases({...});

Метод принимает объект, где:

  • ключ — имя алиаса;
  • значение — конфигурация маски.

Пример:

Inputmask.extendAliases({
    phoneKz: {
        mask: "+7 (999) 999-99-99"
    },

    skuCode: {
        mask: "SKU-999999"
    }
});

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

Inputmask("phoneKz").mask("#phone");
Inputmask("skuCode").mask("#sku");

Структура алиаса

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

Стандартная структура:

Inputmask.extendAliases({
    customAlias: {
        mask: "",
        placeholder: "",
        greedy: false,
        definitions: {},
        oncomplete: function () {},
        onincomplete: function () {},
        validator: function () {},
        postValidation: function () {}
    }
});

Внутри алиаса можно использовать:

  • маски;
  • regex;
  • кастомные определения;
  • события;
  • динамическую логику;
  • функции генерации;
  • условия;
  • preprocess/postprocess обработчики.

Простейший пользовательский алиас

Маска номера договора

Inputmask.extendAliases({
    contractNumber: {
        mask: "CNT-9999-9999"
    }
});

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

Inputmask("contractNumber").mask("#contract");

Результат:

CNT-1234-5678

Алиасы с placeholder

Настройка символов заполнения

Inputmask.extendAliases({
    serialNumber: {
        mask: "SN-999999",
        placeholder: "X"
    }
});

Ввод будет отображаться так:

SN-XXXXXX

Алиасы с кастомными определениями

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

Inputmask.extendAliases({
    productCode: {
        mask: "P-LL-999",
        definitions: {
            "L": {
                validator: "[A-Z]",
                casing: "upper"
            }
        }
    }
});

Примеры:

P-AB-123
P-ZX-999

Алиасы с regex

Использование регулярных выражений

Алиас может быть основан не только на mask, но и на regex.

Inputmask.extendAliases({
    hexColor: {
        regex: "^#[0-9A-Fa-f]{6}$"
    }
});

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

Inputmask("hexColor").mask("#color");

Допустимые значения:

#FFAA00
#00ff99

Алиасы с автоматическим преобразованием регистра

Параметр casing

Inputmask.extendAliases({
    upperArticle: {
        mask: "AAAA-9999",
        casing: "upper"
    }
});

Ввод:

abcd1234

Автоматически преобразуется в:

ABCD-1234

Алиасы с функциями валидации

Проверка бизнес-правил

Inputmask.extendAliases({
    evenCode: {
        mask: "9999",

        postValidation: function(buffer) {
            const value = parseInt(buffer.join(""));

            return value % 2 === 0;
        }
    }
});

Допустимые значения:

2468
4000
8888

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

1357
1111

Алиасы с callback-функциями

Обработка успешного ввода

Inputmask.extendAliases({
    employeeId: {
        mask: "EMP-9999",

        oncomplete: function() {
            console.log("ID заполнен");
        },

        onincomplete: function() {
            console.log("ID заполнен не полностью");
        }
    }
});

Алиасы с динамической маской

Генерация mask через функцию

Inputmask.extendAliases({
    dynamicPhone: {
        mask: function() {
            return [
                "+7 (999) 999-99-99",
                "+1 (999) 999-9999"
            ];
        }
    }
});

Inputmask автоматически выберет подходящий шаблон.

Наследование алиасов

Создание алиаса на основе другого

Алиасы могут наследовать существующие конфигурации.

Inputmask.extendAliases({
    shortDate: {
        alias: "datetime",
        inputFormat: "dd/mm/yyyy"
    }
});

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

Inputmask("shortDate").mask("#date");

Расширение встроенных алиасов

Модификация numeric

Inputmask.extendAliases({
    customCurrency: {
        alias: "numeric",
        groupSeparator: " ",
        radixPoint: ",",
        digits: 2,
        prefix: "₸ "
    }
});

Результат:

₸ 120 500,50

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

Inputmask.extendAliases({
    localPhone: {
        alias: "phone",
        placeholder: "*",
        clearIncomplete: true
    }
});

Использование preprocess и postprocess логики

Предварительная обработка значения

Inputmask.extendAliases({
    trimSpaces: {
        mask: "999999",

        onBeforeMask: function(value) {
            return value.trim();
        }
    }
});

Обработка после удаления маски

Inputmask.extendAliases({
    cleanCode: {
        mask: "999-999",

        onUnMask: function(maskedValue, unmaskedValue) {
            return unmaskedValue;
        }
    }
});

Сложные составные алиасы

Комбинирование нескольких возможностей

Inputmask.extendAliases({
    secureProductCode: {
        mask: "AA-9999-***",

        definitions: {
            "*": {
                validator: "[A-Za-z0-9]"
            }
        },

        casing: "upper",

        placeholder: "_",

        clearIncomplete: true,

        oncomplete: function() {
            console.log("Код принят");
        }
    }
});

Допустимый результат:

AB-1234-X9Q

Использование aliases внутри aliases

Многоуровневая архитектура

Inputmask.extendAliases({
    baseMoney: {
        alias: "numeric",
        digits: 2,
        radixPoint: "."
    },

    dollarMoney: {
        alias: "baseMoney",
        prefix: "$ "
    },

    euroMoney: {
        alias: "baseMoney",
        prefix: "€ "
    }
});

Локализация через алиасы

Маски для разных стран

Inputmask.extendAliases({
    phoneRu: {
        mask: "+7 (999) 999-99-99"
    },

    phoneUs: {
        mask: "+1 (999) 999-9999"
    },

    phoneDe: {
        mask: "+49 9999 999999"
    }
});

Динамический выбор алиаса

Переключение по условию

function getAlias(country) {
    switch(country) {
        case "ru":
            return "phoneRu";

        case "us":
            return "phoneUs";

        case "de":
            return "phoneDe";
    }
}

Inputmask(getAlias("ru")).mask("#phone");

Алиасы для корпоративных приложений

Централизованный каталог масок

Inputmask.extendAliases({

    employeeNumber: {
        mask: "EMP-99999"
    },

    warehouseCode: {
        mask: "WH-999"
    },

    invoiceNumber: {
        mask: "INV-999999"
    },

    departmentCode: {
        mask: "DEP-AAA"
    }

});

Преимущества такого подхода:

  • единый стандарт ввода;
  • централизованное обновление;
  • уменьшение дублирования;
  • упрощение поддержки;
  • единообразие интерфейсов.

Регистрация алиасов по модулям

Разделение по доменным областям

// finance.aliases.js
Inputmask.extendAliases({
    ibanCode: {
        mask: "AA99 9999 9999 9999"
    }
});
// crm.aliases.js
Inputmask.extendAliases({
    customerId: {
        mask: "CUS-999999"
    }
});

Ошибки при создании алиасов

Конфликт имён

Inputmask.extendAliases({
    numeric: {
        mask: "999"
    }
});

Такой код переопределит встроенный алиас numeric.

Это может привести к непредсказуемому поведению.

Слишком сложная логика внутри validator

Плохой пример:

validator: function(chrs) {
    // сложные вычисления
    // сетевые запросы
    // тяжёлая логика
}

Validator вызывается очень часто, поэтому тяжёлые операции ухудшают производительность.

Дублирование конфигурации

Неправильно:

Inputmask.extendAliases({
    phone1: {
        mask: "+7 (999) 999-99-99",
        placeholder: "_"
    },

    phone2: {
        mask: "+7 (999) 999-99-99",
        placeholder: "_"
    }
});

Лучше:

Inputmask.extendAliases({
    basePhone: {
        mask: "+7 (999) 999-99-99",
        placeholder: "_"
    },

    officePhone: {
        alias: "basePhone"
    },

    mobilePhone: {
        alias: "basePhone"
    }
});

Организация библиотеки алиасов

Рекомендуемая структура

/masks
    finance.aliases.js
    crm.aliases.js
    logistics.aliases.js
    common.aliases.js

Именование алиасов

Хорошие практики

Рекомендуется:

invoiceNumber
employeeId
warehouseCode
currencyKzt

Нежелательно:

mask1
test
abc
myMask

Имя алиаса должно отражать его назначение.

Создание универсальных алиасов

Конфигурация через параметры

Inputmask.extendAliases({
    configurableCode: {
        mask: function(opts) {
            return opts.template;
        }
    }
});

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

Inputmask({
    alias: "configurableCode",
    template: "AAA-999"
}).mask("#code");

Алиасы и unmaskedvalue

Работа с чистыми данными

Inputmask.extendAliases({
    cleanPhone: {
        mask: "+7 (999) 999-99-99",
        removeMaskOnSubmit: true
    }
});

При отправке формы:

79991234567

Комбинация alias и regex

Inputmask.extendAliases({
    emailStrict: {
        alias: "email",
        regex: "^[^@]+@company\\.com$"
    }
});

Допустимо:

user@company.com

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

user@gmail.com

Подключение алиасов после загрузки страницы

document.addEventListener("DOMContentLoaded", () => {

    Inputmask.extendAliases({
        userCode: {
            mask: "USR-9999"
        }
    });

    Inputmask("userCode").mask("#user");
});

Повторное использование алиасов в больших проектах

Подход через общий реестр

export const aliases = {

    employeeId: {
        mask: "EMP-99999"
    },

    taxNumber: {
        mask: "TAX-999999"
    }

};

Регистрация:

Inputmask.extendAliases(aliases);

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

Наиболее затратные элементы:

  • сложные регулярные выражения;
  • тяжёлые validator-функции;
  • большое количество alternator;
  • глубокая динамическая логика;
  • постоянные postValidation вычисления.

Оптимизация:

  • минимизация regex;
  • кеширование вычислений;
  • наследование конфигураций;
  • отказ от избыточных callback;
  • разделение крупных масок на специализированные алиасы.

Интеграция с UI-компонентами

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

useEffect(() => {

    Inputmask.extendAliases({
        reactPhone: {
            mask: "+7 (999) 999-99-99"
        }
    });

    Inputmask("reactPhone").mask(inputRef.current);

}, []);

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

mounted() {

    Inputmask.extendAliases({
        vueCode: {
            mask: "VUE-9999"
        }
    });

    Inputmask("vueCode").mask(this.$refs.code);
}

Создание алиасов для API-форматов

UUID

Inputmask.extendAliases({
    uuidMask: {
        mask: "********-****-****-****-************",

        definitions: {
            "*": {
                validator: "[0-9a-fA-F]"
            }
        },

        casing: "lower"
    }
});

JWT-фрагмент

Inputmask.extendAliases({
    jwtSegment: {
        regex: "^[A-Za-z0-9\\-_]+$"
    }
});

Тестирование пользовательских алиасов

Проверка через isValid

Inputmask.isValid(
    "EMP-1234",
    {
        alias: "employeeId"
    }
);

Проверка unmaskedvalue

const im = new Inputmask("cleanPhone");

im.mask("#phone");

console.log(
    im.unmaskedvalue()
);

Отладка пользовательских алиасов

Проверка зарегистрированных конфигураций

console.log(Inputmask.prototype.aliases);

Анализ итоговых настроек

const instance = new Inputmask("employeeId");

console.log(instance.opts);

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

Inputmask.extendAliases({

    companyPhone: {
        mask: "+7 (999) 999-99-99",
        clearIncomplete: true
    },

    companyEmail: {
        alias: "email"
    },

    employeeCard: {
        mask: "EMP-999999"
    },

    warehouseItem: {
        mask: "WH-AAA-9999",
        casing: "upper"
    },

    moneyKzt: {
        alias: "numeric",
        groupSeparator: " ",
        radixPoint: ",",
        digits: 2,
        prefix: "₸ "
    }

});
Оглавление