Улучшить эту документацию ngMessages

Модуль ngMessages предоставляет расширенную поддержку отображения сообщений в шаблонах (обычно в формах или при отрисовке объектов сообщений, которые возвращают данные ключ/значение). Вместо того, чтобы полагаться на код JavaScript и/или сложные инструкции ng-if в шаблоне формы для отображения и скрытия сообщений об ошибках, специфичных для состояния поля ввода, директивы ngMessages и ngMessage предназначены для обработки сложности, наследования и приоритетного упорядочения на основе порядка определения сообщений в шаблоне.

В настоящее время модуль ngMessages содержит только код для директивы ngMessages и директивы ngMessage.

Использование

Директива ngMessages прослушивает коллекцию ключ/значение, которая установлена в атрибуте ngMessages. Поскольку директива ngModel предоставляет объект $error, этот объект ошибок может быть использован с ngMessages для отображения сообщений об ошибках управления более удобным способом, чем с обычными директивами шаблонов Angular.

<form name="myForm">
  <input type="text" ng-model="field" name="myField" required minlength="5" />
  <div ng-messages="myForm.myField.$error">
    <div ng-message="required">You did not enter a field</div>
    <div ng-message="minlength">The value entered is too short</div>
  </div>
</form>

Теперь любые записи ключ/значение, присутствующие в предоставленном объекте (в данном случае $error), будут отображаться директивой ngMessages с помощью внутренней директивы ngMessage (в зависимости от совпадения ключей и значений с атрибутом каждой директивы ngMessage). Другими словами, если ваш объект ошибок содержит следующие данные:

<!-- keep in mind that ngModel automatically sets these error flags -->
myField.$error = { minlength : true, required : false };

Тогда сначала будет отображаться сообщение required. Когда required равно false, сообщение minlength будет отображаться сразу после него (поскольку эти сообщения упорядочены таким образом в HTML-коде шаблона). Приоритет каждого сообщения определяется порядком их присутствия в DOM. Таким образом, вместо того, чтобы пользовательский код JavaScript определял приоритет наличия ошибок перед другими, отображение ошибок обрабатывается в шаблоне.

По умолчанию ngMessages будет отображать только одну ошибку за раз. Однако, если вы хотите отобразить все сообщения, то атрибут ng-messages-multiple может быть использован в элементе, содержащем директиву ngMessages, для этого.

<div ng-messages="myForm.myField.$error" ng-messages-multiple>...</div>

Использование и перезапись сообщений

В дополнение к упорядочению, ngMessages также позволяет включать сообщения из удаленного или встроенного шаблона. Это позволяет повторно использовать общие наборы сообщений в разных частях приложения.

<script type="text/ng-template" id="error-messages">
  <div ng-message="required">This field is required</div>
  <div ng-message="minlength">This field is too short</div>
</script>
<div ng-messages="myForm.myField.$error" ng-messages-include="error-messages"></div>

Однако, включение общих сообщений может быть недостаточно для соответствия всем полям ввода, поэтому ngMessages предоставляет возможность переопределять сообщения, определенные в удаленном шаблоне, переопределяя их внутри контейнера директивы.

<!-- a generic template of error messages known as "my-custom-messages" -->
<script type="text/ng-template" id="my-custom-messages">
  <div ng-message="required">This field is required</div>
  <div ng-message="minlength">This field is too short</div>
</script>

<form name="myForm">
  <input type="email"
         id="email"
         name="myEmail"
         ng-model="email"
         minlength="5"
         required />

  <div ng-messages="myForm.myEmail.$error" ng-messages-include="my-custom-messages">
    <!-- this required message has overridden the template message -->
    <div ng-message="required">You did not enter your email address</div>

    <!-- this is a brand new message and will appear last in the prioritization -->
    <div ng-message="email">Your email address is invalid</div>
  </div>
</form>

В примере HTML-кода выше сообщение, установленное для required, переопределяет соответствующее сообщение required, определенное в удаленном шаблоне. Таким образом, для конкретных полей ввода (например, адресов электронной почты, полей дат, полей автозаполнения и т. д.) могут быть применены специализированные сообщения об ошибках, а для обработки других, более общих ошибок ввода могут использоваться более общие сообщения.

Анимации

Если модуль ngAnimate активен в приложении, то директивы ngMessages и ngMessage будут запускать анимации всякий раз, когда директива ngMessages добавляет или удаляет сообщения из DOM.

Всякий раз, когда директива ngMessages содержит одно или несколько видимых сообщений, CSS-класс .ng-active будет добавлен к элементу. CSS-класс .ng-inactive будет применен, когда анимации отсутствуют. Таким образом, CSS-переходы и ключевые кадры, а также анимации JavaScript могут быть подключены к анимациям всякий раз, когда эти классы добавляются/удаляются.

Предположим, что наш HTML-код для контейнера сообщений выглядит следующим образом:

<div ng-messages="myMessages" class="my-messages">
  <div ng-message="alert" class="some-message">...</div>
  <div ng-message="fail" class="some-message">...</div>
</div>

Тогда код CSS-анимации для контейнера сообщений выглядит следующим образом:

.my-messages {
  transition:1s linear all;
}
.my-messages.ng-active {
  // messages are visible
}
.my-messages.ng-inactive {
  // messages are hidden
}

Всякий раз, когда внутреннее сообщение прикрепляется (становится видимым) или удаляется (становится скрытым), анимация входа и выхода запускается для каждого элемента, связанного с директивой ngMessage.

Поэтому, код CSS для внутренних сообщений выглядит следующим образом:

.some-message {
  transition:1s linear all;
}

.some-message.ng-enter {}
.some-message.ng-enter.ng-enter-active {}

.some-message.ng-leave {}
.some-message.ng-leave.ng-leave-active {}

Нажмите здесь, чтобы узнать, как использовать анимации JavaScript или узнать больше об ngAnimate.

Установка

Сначала включите angular-messages.js в ваш HTML:

<script src="angular.js">
<script src="angular-messages.js">

Вы можете загрузить этот файл из следующих мест:

• Google CDN
  Например: //ajax.googleapis.com/ajax/libs/angularjs/X.Y.Z/angular-messages.js
• Bower
  Например:

  bower install angular-messages@X.Y.Z

• code.angularjs.org
  Например:

  "//code.angularjs.org/X.Y.Z/angular-messages.js"

где X.Y.Z — версия AngularJS, которую вы используете.

Затем загрузите модуль в ваше приложение, добавив его как зависимый модуль:

angular.module('app', ['ngMessages']);

С этим вы готовы приступить к работе!