Управляющие элементы (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, вы можете легко заменить или удалить встроенные валидаторы, если это необходимо. Следующий пример показывает, как переопределить валидатор email в input[email] с помощью пользовательской директивы, чтобы он требовал наличия определённого доменного имени верхнего уровня, example.com. Обратите внимание, что вы можете альтернативно использовать ng-pattern для дальнейшего ограничения валидации.

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

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

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

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

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

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