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

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

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

• $validate();

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

• $commitViewValue();

  Подтвердить ожидающее обновление $modelValue.

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

• $setViewValue(value, trigger);

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

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

  Например, input вызывает его, когда изменяется значение ввода, и select вызывает его, когда выбран параметр.

  Если новое value является объектом (а не строкой или числом), мы должны создать копию объекта перед передачей его в $setViewValue. Это связано с тем, что ngModel не выполняет глубокое наблюдение за объектами, он только ищет изменение идентичности. Если вы измените только свойство объекта, то ngModel не поймет, что объект изменился, и не вызовет конвейеры $parsers и $validators.

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

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

  Наконец, вызываются все зарегистрированные обработчики изменений в списке $viewChangeListeners.

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

  Обратите внимание, что вызов этой функции не вызывает $digest.

  Параметры

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

Свойства

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

  string

  Фактическое строковое значение в представлении.

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

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

• $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.