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

Элементы управления (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 миллисекунд после последнего изменения.

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

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

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

Каждая функция в объекте $validators получает modelValue и viewValue в качестве параметров. Затем Angular вызовет $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.

Изменение встроенных валидаторов

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

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

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

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

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

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

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