Плагин Knockout Validation для Knockout.js

Валидация пользовательского ввода является достаточно общей задачей, в решении которой, есть потребность почти у каждого веб-приложения. Knockout Validation — это самый популярный Knockout плагин для валидации на текущий момент. У него на 50% больше звёзд на GitHub, чем у любого другого проекта, связанного с валидацией в Knockout.

1. Общие сведения

Плагин Knockout Validation создаёт несколько расширителей и обработчиков привязки, которые предназначены для упрощения валидации HTML-формы. Начать работать с Knockout Validation очень просто. При использовании плагина добавляются расширители, которые применяют логику валидации к наблюдаемым объектам, не заменяя их:

var requiredValue = ko.observable().extend({ required: true });
var multipleValidationValue = ko.observable().extend({
    required: true,
    minLength: 3,
    pattern: {
        message: 'Эй, это не соответствует моему шаблону!',
        params: '^[A-Z0-9].$'
    }
});

Привязка к значениям расширителей валидации выполняется с помощью стандартной привязки value:

<input data-bind="value: requiredValue">

Knockout Validation при изменении значений элементов ввода с помощью привязок отображает предупреждения при недопустимых значениях. По умолчанию поведение отображения поместит элемент <span>, который содержит любые ошибки, после связанного со значением элемента ввода. При допустимом значении элемент <span> с сообщением об ошибке будет скрыт, а при недопустимом значении — показан.

Эта автоматическая вставка ошибок может быть отключена, если ты хочешь вручную поместить сообщение валидации в представление. Для этого используй привязку validationMessage, которая имеет такое же поведение, что и используемый по умолчанию элемент <span>.

2. Правила валидации по умолчанию

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

var myObj = ko.observable().extend({ required: true });
var myObj = ko.observable().extend({ number: true, min: 10, max: 30 });
var myObj = ko.observable().extend({ number: true }).extend({ min: 10, max: 30 });

Правила по умолчанию охватывают большинство стандартных случаев проверки значений:

• минимальное и максимальное числовое значение,
• минимальная и максимальная длина строки,
• шаблон регулярного выражения,
• дата,
• значение равенства и другие.

3. Настройка параметров валидации

Поведение плагина Knockout Validation очень настраиваемо. Ниже представлены наиболее полезные параметры:

• insertMessages (по умолчанию: true) — если true, вставляется либо элемент <span>, либо шаблон, указанный привязкой messageTemplate, после любого элемента, который использует привязку value с валидацией наблюдаемого объекта.
• errorElementClass (по умолчанию: validationElement) — это класс, который применяется к элементам ввода, когда проверенные данные в наблюдаемом объекте недопустимы.
• messagesOnModified (по умолчанию: true) — если true, сообщения валидации не будут отображаться, пока значения в наблюдаемых объектах не будут модифицированы. Другими словами, сообщения будут скрыты до тех пор, пока пользователь не начнёт взаимодействовать с формой.
• messageTemplate (по умолчанию: null) — это идентификатор элемента сценария, который будет использоваться в качестве шаблона сообщения валидации, вместо вставки сообщения в <span>.

Параметры валидации можно установить глобально, передав объект в ko.validation.init:

ko.validation.init({
    insertMessages: false,
    errorElementClass: 'text-danger'
});

Параметры также могут быть установлены контекстно с помощью связывания validationOption или передавая объект конфигурации в ko.applyBindingsWithValidation:

ko.applyBindingsWithValidation(viewModel, rootNode, {
    insertMessages: false,
    errorElementClass: 'text-danger'
});

4. Привязки валидации

Knockout Validation добавляет несколько привязок валидации, которые помогают отображать ошибки валидации. Привязка validationMessage отображает сообщение об ошибке при валидации наблюдаемых объектов, если их значения являются недопустимыми. Когда значение является допустимым, элемент скрыт:

<div>
    <input type="text" data-bind="value: someValue">
    <p data-bind="validationMessage: someValue"></p>
</div>

Привязка validationElement устанавливает значение сообщения об ошибке в атрибут title связанного элемента, это удобно использовать для отображения всплывающих подсказок. Если параметр валидации decorateInputElement имеет значение true, то привязка также применяет класс из параметра errorElementClass (по умолчанию: validationElement) на связанный элемент ввода:

<div>
    <label data-bind="validationElement: someValue">
        <input type="text" data-bind="value: someValue">
    </label>
</div>

Привязка validationOptions применяет указанные параметры валидации ко всем потомкам её DOM-узлов и принимает тот же формат объекта, который используется при настройке параметров валидации:

<div data-bind="validationOptions: { insertMessages: false }">
    <input type="text" data-bind="value: someValue">
    <p data-bind="validationMessage: someValue"></p>
</div>

5. Создание пользовательских правил валидации

Пользовательские правила могут быть глобальными и встроенными (анонимными). Глобальные правила могут повторно использоваться несколькими расширителями, а встроенные лишь однажды, так как относятся к одному наблюдаемому объекту.

Глобальное правило валидации состоит из 2-х компонентов:

• validator — функция валидатора,
• message — сообщение по умолчанию.

Добавление новых глобальных правил валидации осуществляется путём добавления объекта правила валидации к объекту ko.validation.rules:

ko.validation.rules['contains'] = {
    validator: function (val, substring) {
        return val.indexof(substring) !== -1;
    },
    message: 'Поле должно содержать {0}'
};

Функция validator получает два аргумента:

• значение наблюдаемого объекта,
• значение, переданное расширителю валидации.

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

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

ko.validation.registerExtenders();

Затем новые правила могут быть использованы в качестве расширителей наблюдаемых объектов:

var title = ko.observable().extend({ contains: 'Sr.' });

Пользовательские правила валидации можно также встраивать в расширитель валидации, передав в него объект правила валидации:

var title = ko.observable().extend({
    validation: {
        validator: function (val, substring) {
            return val.indexof(substring) !== -1;
        },
        message: 'Поле должно содержать {0}',
        params: 'Sr.'
    }
});

Встроенное правило валидации состоит из 3-х компонентов:

• validator — функция валидатора,
• message — сообщение по умолчанию,
• params — 2-ой аргумент для функции validator.

При использовании встроенного (анонимного) правила валидации второй параметр функции validator определяется свойством params этого же правила валидации.

Ниже представлен пример работы формы регистрации с плагином Knockout Validation.