Улучшить эту документацию Просмотреть исходный код 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, применит его для обновления 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.