Улучшить эту документациюФормы

Элементы управления (input, select, textarea) — это способы ввода данных пользователем. Форма — это набор элементов управления, предназначенных для группировки связанных элементов управления.

Формы и элементы управления предоставляют функции валидации, чтобы пользователь мог получить уведомление о некорректном вводе до отправки формы. Это обеспечивает лучший пользовательский опыт по сравнению с одной только валидацией на стороне сервера, так как пользователь получает мгновенную обратную связь о том, как исправить ошибку. Имейте в виду, что, хотя валидация на стороне клиента играет важную роль в обеспечении хорошего пользовательского опыта, ее легко обойти, и поэтому ей нельзя доверять. Для безопасного приложения по-прежнему необходима валидация на стороне сервера.

Простая форма

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

Обратите внимание, что novalidate используется для отключения собственной валидации формы браузера.

Значение ngModel не будет установлено, если оно не пройдёт валидацию для поля ввода. Например: поля типа email должны иметь значение в виде user@domain.

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

Для стилизации формы и элементов управления ngModel добавляет следующие классы CSS:

• ng-valid: модель валидна
• ng-invalid: модель невалидна
• ng-valid-[key]: для каждого валидного ключа, добавленного $setValidity
• ng-invalid-[key]: для каждого невалидного ключа, добавленного $setValidity
• ng-pristine: элемент управления еще не взаимодействовал с пользователем
• ng-dirty: элемент управления взаимодействовал с пользователем
• ng-touched: элемент управления был потерян фокуса
• ng-untouched: элемент управления не был потерян фокуса
• ng-pending: все $asyncValidators не выполнены

Следующий пример использует CSS для отображения валидности каждого элемента управления формой. В примере и user.name и user.email требуются, но отображаются с красным фоном только после того, как вход потеряет фокус. Это гарантирует, что пользователь не будет отвлечен ошибкой до тех пор, пока не взаимодействует с элементом управления и не выполнит его валидацию.

Привязка к состоянию формы и элемента управления

Форма является экземпляром FormController. Экземпляр формы можно выборочно опубликовать в область видимости с помощью атрибута name.

Аналогично, элемент управления ввода, у которого есть директива ngModel, содержит экземпляр NgModelController. Такой экземпляр элемента управления можно опубликовать в качестве свойства экземпляра формы с помощью атрибута name на элементе управления ввода. Атрибут name указывает имя свойства в экземпляре формы.

Это подразумевает, что внутреннее состояние как формы, так и элемента управления доступно для привязки в представлении с помощью стандартных примитивов привязки.

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

• Пользовательское сообщение об ошибке отображается после того, как пользователь взаимодействовал с элементом управления (т. е. когда $touched установлено)
• Пользовательское сообщение об ошибке отображается при отправке формы ($submitted установлено), даже если пользователь не взаимодействовал с элементом управления

Настраиваемые триггеры обновления модели

По умолчанию любое изменение содержимого инициирует обновление модели и валидацию формы. Вы можете настроить это поведение, используя директиву ngModelOptions, чтобы привязываться только к определенному списку событий. Например, ng-model-options="{ updateOn: 'blur' }" будет обновлять и валидировать только после того, как элемент управления потеряет фокус. Вы можете задать несколько событий, используя список, разделенный пробелом. Например, ng-model-options="{ updateOn: 'mousedown blur' }".

Если вы хотите сохранить поведение по умолчанию и просто добавить новые события, которые могут инициировать обновление модели и валидацию, добавьте «default» в качестве одного из заданных событий.

Например, ng-model-options="{ updateOn: 'default blur' }"

Следующий пример показывает, как переопределить непосредственные обновления. Изменения вводах внутри формы будут обновлять модель только тогда, когда элемент управления потеряет фокус (событие blur).

Немедленные (задержки) обновления модели

Вы можете отложить обновление/валидацию модели, используя ключ debounce с директивой ngModelOptions. Эта задержка также будет применяться к парсерам, валидаторам и флагам модели, таким как $dirty или $pristine.

Например, ng-model-options="{ debounce: 500 }" будет ждать полсекунды после последнего изменения содержимого, прежде чем инициировать обновление модели и валидацию формы.

Если используются настраиваемые триггеры, настраиваемые тайм-ауты задержки можно задать для каждого события с помощью объекта в debounce. Это может быть полезно для принудительного выполнения немедленных обновлений в некоторых особых случаях (например, событий blur).

Например, ng-model-options="{ updateOn: 'default blur', debounce: { default: 500, blur: 0 } }"

Если эти атрибуты добавлены к элементу, они будут применяться ко всем дочерним элементам и элементам управления, унаследованным от него, если они не переопределены.

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

Настройка валидации

AngularJS предоставляет базовые реализации для большинства общих типов HTML5 input: (text, number, url, email, date, radio, checkbox), а также некоторые директивы для валидации (required, pattern, minlength, maxlength, min, max).

С помощью настраиваемой директивы вы можете добавить собственные функции валидации в объект $validators объекта ngModelController. Для получения контроллера вам нужно его запросить в директиве, как показано в примере ниже.

Каждая функция в объекте $validators получает modelValue и viewValue в качестве параметров. Затем AngularJS выполнит $setValidity внутри с возвращаемым значением функции (true: валидно, false: невалидно). Функции валидации выполняются каждый раз, когда изменяется вход (вызывается $setViewValue), или всякий раз, когда изменяется связанное model. Валидация происходит после успешного выполнения $parsers и $formatters, соответственно. Неудачные валидаторы хранятся по ключу в ngModelController.$error.

Кроме того, есть объект $asyncValidators, который обрабатывает асинхронную валидацию, например, выполнение запроса $http на сервер. Функции, добавленные в объект, должны возвращать обещание, которое должно быть resolved при валидности или rejected при невалидности. Процессируемые асинхронные валидации хранятся по ключу в ngModelController.$pending.

В приведенном ниже примере мы создаем две директивы:

• Директива integer, которая проверяет, является ли вход действительным целым числом. Например, 1.23 — это невалидное значение, поскольку оно содержит дробь. Обратите внимание, что мы валидируем viewValue (строковое значение элемента управления), а не modelValue. Это связано с тем, что input[number] преобразует viewValue в число при выполнении $parsers.

• Директива username, которая асинхронно проверяет, не используется ли введенное пользователем значение. Мы моделируем запрос на сервер с помощью $q deferred.

Модификация встроенных валидаторов

Поскольку сам AngularJS использует $validators, вы можете легко заменить или удалить встроенные валидаторы, если это необходимо. Следующий пример показывает, как переопределить валидатор электронной почты в input[email] из настраиваемой директивы, чтобы потребовать наличие определенного доменного имени верхнего уровня, example.com. Обратите внимание, что вы можете альтернативно использовать ng-pattern для дальнейшей ограничения валидации.

Реализация настраиваемых элементов управления формой (используя ngModel)

AngularJS реализует все основные элементы управления формой HTML (input, select, textarea), что должно быть достаточным для большинства случаев. Однако, если вам нужна большая гибкость, вы можете написать собственный элемент управления формой в виде директивы.

Для работы пользовательского элемента управления с ngModel и для достижения двусторонней привязки данных он должен:

• Реализовать метод $render, который отвечает за отображение данных после прохождения NgModelController.$formatters,
• вызвать метод $setViewValue, всякий раз, когда пользователь взаимодействует с элементом управления, и модель нуждается в обновлении. Это обычно выполняется внутри обработчика событий DOM.

См. $compileProvider.directive для получения дополнительной информации.

Следующий пример показывает, как добавить двустороннюю привязку данных к элементам contentEditable.