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

• $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 не синхронизирован со значением ngModel $modelValue.

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

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