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

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