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

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

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

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

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

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

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

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