Улучшить эту документацию Просмотреть исходный код ngModel.NgModelController

Методы

• $render();

  Вызывается, когда требуется обновить представление. Ожидается, что пользователь директивы ng-model реализует этот метод.

  Метод $render() вызывается в следующих ситуациях:

  • $rollbackViewValue() вызывается. Если мы отменяем значение представления до последнего сохраненного значения, то $render() вызывается для обновления элемента управления вводом.
  • Значение, на которое ссылается ng-model, изменено программно, и значения $modelValue и $viewValue отличаются от предыдущих.

  Поскольку ng-model не выполняет глубокий отслеживания, $render() вызывается только в том случае, если значения $modelValue и $viewValue фактически отличаются от предыдущих. Если $modelValue или $viewValue являются объектами (а не строкой или числом), то $render() не будет вызван, если вы измените только свойство объектов.

• $isEmpty(value);

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

  Например, директива required использует это для определения, содержит ли элемент ввода данные или нет.

  Функция по умолчанию $isEmpty проверяет, является ли значение undefined, '', null или NaN.

  Вы можете переопределить эту функцию для директивы ввода, у которой понятие пустого значения отличается от стандартного. Директива checkboxInputType делает это, потому что в её случае значение false подразумевает пустое значение.

  Параметры

  Параметр	Тип	Подробности
  value	*	Значение элемента ввода, проверяемого на пустоту.

  Возвращаемое значение

  boolean

  True, если value "пустое".

• $setValidity(validationErrorKey, isValid);

  Изменяет состояние валидности и уведомляет форму.

  Этот метод можно вызывать внутри $parsers/$formatters или в кастомной реализации валидации. Однако в большинстве случаев достаточно использовать коллекции ngModel.$validators и ngModel.$asyncValidators, которые вызовут $setValidity автоматически.

  Параметры

  Параметр	Тип	Подробности
  validationErrorKey	string	Имя валидатора. Ключ validationErrorKey будет назначен либо $error[validationErrorKey], либо $pending[validationErrorKey] (для невыполненных $asyncValidators), чтобы он был доступен для привязки данных. Ключ validationErrorKey должен быть в camelCase и будет преобразован в dash-case для имени класса. Пример: myError приведет к классам ng-valid-my-error и ng-invalid-my-error, и к нему можно будет обратиться как к {{someForm.someControl.$error.myError}}.
  isValid	boolean	Является ли текущее состояние валидным (true), невалидным (false), ожидающим (undefined) или пропущенным (null). Ожидание используется для невыполненных $asyncValidators. Пропущено используется Angular, когда валидаторы не выполняются из-за ошибок разбора и когда $asyncValidators не выполняются, потому что любой из $validators завершился неудачно.

• $setPristine();

  Устанавливает элемент управления в первоначальное состояние.

  Этот метод можно вызвать, чтобы удалить класс ng-dirty и установить элемент управления в первоначальное состояние (класс ng-pristine). Модель считается первоначальной, если элемент управления не был изменён с момента первой компиляции.

• $setDirty();

  Устанавливает элемент управления в грязное состояние.

  Этот метод можно вызвать, чтобы удалить класс ng-pristine и установить элемент управления в грязное состояние (класс ng-dirty). Модель считается грязной, если элемент управления был изменён с момента первой компиляции.

• $setUntouched();

  Устанавливает элемент управления в нетронутое состояние.

  Этот метод можно вызвать, чтобы удалить класс ng-touched и установить элемент управления в нетронутое состояние (класс ng-untouched). При компиляции модель по умолчанию устанавливается как нетронутая, однако эту функцию можно использовать для восстановления этого состояния, если модель уже была затронута пользователем.

• $setTouched();

  Устанавливает элемент управления в состояние "затронуто".

  Этот метод можно вызвать, чтобы удалить класс ng-untouched и установить элемент управления в состояние "затронуто" (класс ng-touched). Модель считается затронутой, когда пользователь впервые сфокусировался на элементе управления, а затем переместил фокус от элемента управления (событие blur).

• $rollbackViewValue();

  Отменить обновление и сбросить значение элемента ввода, чтобы предотвратить обновление $modelValue, которое может быть вызвано ожидающим отложенным событием или потому, что элемент ввода ожидает какого-либо будущего события.

  Если у вас есть элемент ввода, который использует ng-model-options для настройки отложенных обновлений или обновлений, зависящих от специальных событий, таких как blur, может быть период, когда $viewValue не синхронизирован со значением $modelValue ngModel.

  В этом случае вы можете использовать $rollbackViewValue() для отмены отложенного/будущего обновления и сброса значения элемента ввода до последнего сохранённого значения.

  Также могут возникнуть трудности, если вы попытаетесь программно обновить значение $modelValue ngModel до разрешения/происхождения этих отложенных/будущих событий, потому что механизм проверки изменений Angular не может определить, действительно ли модель изменилась.

  Метод $rollbackViewValue() следует вызывать перед программно изменяющим значение модели элемента ввода, который может иметь такие события в ожидании. Это важно для обеспечения того, что поле ввода будет обновлено новым значением модели и любые ожидающие операции будут отменены.

• $validate();

  Выполняет каждый зарегистрированный валидатор (сначала синхронные, затем асинхронные). Если валидность меняется на невалидную, модель будет установлена в undefined, если ngModelOptions.allowInvalid не true. Если валидность меняется на валидную, она устанавливает модель в последнее доступное валидное $modelValue, т. е. последнее проанализированное значение или последнее значение, установленное из области видимости.

• $commitViewValue();

  Зафиксировать ожидающее обновление $modelValue.

  Обновления могут ожидать из-за отложенного события или потому, что элемент ввода ожидает некоторое будущее событие, определенное в ng-model-options. Этот метод редко используется, так как NgModelController обычно обрабатывает вызов этого метода в ответ на события ввода.

• $setViewValue(value, trigger);

  Обновить значение представления.

  Этот метод должен вызываться, когда элемент управления хочет изменить значение представления; как правило, это делается из обработчика события DOM. Например, директива input вызывает его, когда значение элемента ввода изменяется, и select вызывает его, когда выбран пункт.

  Когда $setViewValue вызывается, новое значение value ставится в очередь на подтверждение через каналы $parsers и $validators. Если не указаны специальные параметры ngModelOptions, то ставимое значение отправляется сразу на обработку, после чего применяется к $modelValue и, затем, к выражению, указанному в атрибуте ng-model. Наконец, вызываются все зарегистрированные обработчики изменений в списке $viewChangeListeners.

  В случае использования директивы ngModelOptions с updateOn и триггер default не указан, все эти действия остаются в ожидании до тех пор, пока одно из событий updateOn не будет сгенерировано на элементе DOM. Все эти действия будут отложены, если в директиве ngModelOptions используется настройка отложенного вызова для этого конкретного события. Обратите внимание, что событие $digest будет сгенерировано только после срабатывания событий updateOn, или если указан debounce, после завершения таймера.

  При использовании со стандартными элементами ввода значение представления всегда будет строкой (которая в некоторых случаях анализируется в другой тип, такой как объект Date для input[date]). Однако пользовательские элементы управления также могут передавать объекты в этот метод. В этом случае необходимо сделать копию объекта перед передачей его в $setViewValue. Это потому, что ngModel не выполняет глубокий отслеживания объектов, он только проверяет изменение идентичности. Если вы измените только свойство объекта, ngModel не поймёт, что объект изменился, и не вызовет каналы $parsers и $validators. По этой причине не следует изменять свойства копии после её передачи в $setViewValue. В противном случае вы можете вызвать неверное изменение значения модели в области видимости.

  В любом случае значение, переданное в метод, должно всегда отражать текущее значение элемента управления. Например, если вы вызываете $setViewValue для элемента ввода, вы должны передать значение элемента ввода DOM. В противном случае элемент управления и модель области видимости станут не синхронизированными. Также важно отметить, что $setViewValue не вызывает $render или каким-либо образом не изменяет значение элемента управления DOM. Если мы хотим программно изменить значение элемента управления DOM, мы должны обновить выражение области видимости ngModel. Его новое значение будет взято контроллером модели, который передаст его через каналы $formatters, $render для обновления DOM и, наконец, вызовет $validate на нём.

  Параметры

  Параметр	Тип	Подробности
  value	*	Значение из представления.
  trigger	string	Событие, вызвавшее обновление.

Свойства

• Значение представления

  *	Фактическое значение из представления элемента управления. Для элементов input, это строка. См. ngModel.NgModelController для получения информации о том, когда устанавливается $viewValue.

• Значение модели

  *	Значение в модели, к которой привязан элемент управления.

• $parsers

  Array.<Function>

  Массив функций, которые выполняются как конвейер, всякий раз, когда элемент управления считывает значение из DOM. Функции вызываются в порядке массива, каждая возвращает своё значение, передавая его следующей. Последнее возвращаемое значение передаётся в коллекцию $validators. Парсеры используются для очистки/преобразования $viewValue. Возвращение undefined из парсера означает ошибку парсинга. В этом случае никакие $validators не будут выполнены, и ngModel будет установлено в undefined, если ngModelOptions.allowInvalid не установлено в значение true. Ошибка парсинга сохраняется в ngModel.$error.parse.

• $formatters

  Array.<Function>

  Массив функций, которые выполняются как конвейер всякий раз, когда изменяется значение модели. Функции вызываются в обратном порядке массива, каждая передаёт значение следующей. Последнее возвращённое значение используется в качестве фактического значения DOM. Используется для форматирования/преобразования значений для отображения в элементе управления. function formatter(value) { if (value) { return value.toUpperCase(); } } ngModel.$formatters.push(formatter);

• $validators

  Object.<string, function>

  Коллекция валидаторов, которые применяются всякий раз, когда изменяется значение модели. Значение ключа в объекте относится к имени валидатора, а функция — к операции валидации. Операция валидации получает значение модели в качестве аргумента и должна возвращать true или false в зависимости от результата валидации. ngModel.$validators.validCharacters = function(modelValue, viewValue) { var value = modelValue || viewValue; return /[0-9]+/.test(value) && /[a-z]+/.test(value) && /[A-Z]+/.test(value) && /\W+/.test(value); };

• $asyncValidators

  Object.<string, function>

  Коллекция валидаций, которые должны выполнить асинхронную валидацию (например, запрос HTTP). Функция валидации, которая предоставляется, должна возвращать промис при выполнении во время процесса валидации модели. После того, как промис выполнен, статус валидации будет установлен в true при успехе и в false при отклонении. Когда триггерируются асинхронные валидаторы, каждый из них запускается параллельно, а значение модели обновляется только после того, как все валидаторы будут выполнены. Пока асинхронный валидатор не выполнен, его ключ добавляется к свойству $pending контроллера. Кроме того, все асинхронные валидаторы будут запущены только после того, как будут пройдены все синхронные валидаторы. Обратите внимание, что если используется $http, то важно, чтобы сервер возвращал успешный HTTP-код ответа, чтобы выполнить валидацию, и уровень состояния 4xx для отклонения валидации. ngModel.$asyncValidators.uniqueUsername = function(modelValue, viewValue) { var value = modelValue || viewValue; // Lookup user by username return $http.get('/api/users/' + value). then(function resolved() { //username exists, this means validation fails return $q.reject('exists'); }, function rejected() { //username does not exist, therefore this validation passes return true; }); };

• $viewChangeListeners

  Array.<Function>

  Массив функций, которые выполняются всякий раз, когда изменяется значение представления. Он вызывается без аргументов, а его возвращаемое значение игнорируется. Это можно использовать вместо дополнительных $watches по отношению к значению модели.

• $error

  Object

  Хеш-объект со всеми идентификаторами невалидных валидаторов в качестве ключей.

• $pending

  Object

  Хеш-объект со всеми идентификаторами ожидающих валидаторов в качестве ключей.

• $untouched

  boolean

  True, если элемент управления еще не потерял фокус.

• $touched

  boolean

  True, если элемент управления потерял фокус.

• $pristine

  boolean

  True, если пользователь еще не взаимодействовал с элементом управления.

• $dirty

  boolean

  True, если пользователь уже взаимодействовал с элементом управления.

• $valid

  boolean

  True, если ошибок нет.

• $invalid

  boolean

  True, если есть хотя бы одна ошибка в элементе управления.

• $name

  string

  Атрибут name элемента управления.

В этом примере показано, как использовать NgModelController с пользовательским элементом управления для достижения привязки данных. Обратите внимание, как различные директивы (contenteditable, ng-model, и required) работают вместе для достижения желаемого результата.

contenteditable — это атрибут HTML5, который указывает браузеру, что содержимое элемента можно редактировать пользователем непосредственно.

Здесь используется служба $sce и модуль $sanitize, чтобы автоматически удалять «плохое» содержимое, например, встроенные обработчики событий (например, <span onclick="...">). Однако, так как мы используем $sce, модель по-прежнему может предоставить небезопасное содержимое, если она отметит это содержимое с помощью сервиса $sce.