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

  Истина, если value является "пустым".

• $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 до того, как эти отложенные/будущие события будут разрешены/произойдут, так как механизм проверки на изменения AngularJS не может определить, действительно ли модель изменилась или нет.

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

  Пример

• $validate();

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

• $commitViewValue();

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

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

• $setViewValue(value, trigger);

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

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

  Когда $setViewValue вызывается, новое value будет подготовлено к фиксации через $parsers и $validators конвейеры. Если нет специальных ngModelOptions, то значение отправляется непосредственно на обработку через $parsers конвейер. После этого вызываются $validators и $asyncValidators, и значение применяется к $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	Событие, которое вызвало обновление.

• $overrideModelOptions(options);

  Программно переопределить текущие параметры модели.

  Предыдущее значение ModelOptions не будет изменено. Вместо этого новый объект ModelOptions унаследует от предыдущего, переопределяя или наследуя настройки, определённые в заданном параметре.

  См. ngModelOptions для информации о том, какие параметры можно указать и как работает наследование параметров модели.

  Примечание: эта функция влияет только на параметры, заданные на ngModelController, а не на параметры в директиве ngModelOptions, из которых они могут быть изначально получены.

  Примечание: нельзя переопределить параметр getterSetter.

  Параметры

  Параметр	Тип	Подробности
  options	Object	словарь настроек для переопределения предыдущих параметров

• $processModelValue();

  Выполняет обработку конвейера модель -> представление для текущего $modelValue.

  Этот метод выполняет следующие действия:

  • значение $modelValue проходит через $formatters и результат устанавливается в $viewValue
  • на элементе устанавливается класс ng-empty или ng-not-empty
  • если значение $viewValue изменилось:
    • $render вызывается для управления
    • $validators выполняются, и статус валидации устанавливается.

  Этот метод вызывается внутри ngModel, когда изменяется связанное значение области видимости. Разработчики приложений обычно не должны вызывать эту функцию самостоятельно.

  Эта функция может быть использована, когда значение $viewValue или рендеренное значение DOM не отформатированы должным образом, и $modelValue необходимо снова пройти через $formatters.

  Пример

  Рассмотрим текстовое поле с автодополнением (для фруктов), где элементы — это объекты с именем и идентификатором. Пользователь вводит ap и затем выбирает Apricot из списка. На основе этого виджет автодополнения вызовет $setViewValue({name: 'Apricot', id: 443}), но рендеренное значение всё ещё будет ap. Затем виджет может вызвать ctrl.$processModelValue() для повторного выполнения конвейера модель -> представление, что отформатирует объект в строку Apricot, обновит $viewValue и, наконец, отобразит его в DOM.

• $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. Пропуск используется AngularJS, когда валидаторы не запускаются из-за ошибок парсинга и когда $asyncValidators не выполняются, поскольку какой-либо из $validators завершился неудачей.

Свойства

• $viewValue

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

• $modelValue

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

• $parsers

  Array.<Function>

  Массив функций, выполняемых последовательно, всякий раз, когда элемент управления обновляет ngModelController новым $viewValue из DOM, обычно при взаимодействии пользователя. Смотрите $setViewValue() для подробного объяснения жизненного цикла. Обратите внимание, что $parsers не вызываются, когда связанное выражение ngModel изменяется программно. Функции вызываются в порядке массива, каждая передавая свое возвращаемое значение следующей функции. Последнее возвращаемое значение передается в коллекцию $validators. Парсеры используются для очистки/преобразования $viewValue. Возвращение undefined от парсера означает возникновение ошибки парсинга. В этом случае никакие $validators не будут выполнены, и ngModel будет установлено в undefined, если не установлено ngModelOptions.allowInvalid в true. Ошибка парсинга хранится в ngModel.$error.parse. Этот простой пример демонстрирует парсер, который преобразует значение ввода текста в нижний регистр: function parse(value) { if (value) { return value.toLowerCase(); } } ngModelController.$parsers.push(parse);

• $formatters

  Array.<Function>

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

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

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

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