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

Установка

Сначала получите файл:

• Google CDN например,

  "//ajax.googleapis.com/ajax/libs/angularjs/X.Y.Z/angular-messages.js"

• NPM например,

  npm install --save angular-messages@X.Y.Z

  или

  yarn add angular-messages@X.Y.Z

• 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-messages.js в свой HTML:

<script src="path/to/angular.js"></script>
<script src="path/to/angular-messages.js"></script>

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

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

Теперь вы готовы к работе!

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

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

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

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

Дочерние элементы директивы ngMessages сопоставляются с ключами коллекции с помощью директивы ngMessage или ngMessageExp. Значение этих атрибутов должно соответствовать ключу в коллекции, предоставляемой директивой ngMessages.

Рассмотрим следующий пример, иллюстрирующий типичный сценарий использования ngMessages. В форме myForm у нас есть текстовое поле с именем myField, связанное с переменной области видимости field с помощью директивы ngModel.

Поле myField — это обязательное поле ввода типа email с максимальной длиной 15 символов.

<form name="myForm">
  <label>
    Enter text:
    <input type="email" ng-model="field" name="myField" required maxlength="15" />
  </label>
  <div ng-messages="myForm.myField.$error" role="alert">
    <div ng-message="required">Please enter a value for this field.</div>
    <div ng-message="email">This field must be a valid email address.</div>
    <div ng-message="maxlength">This field can be at most 15 characters long.</div>
  </div>
</form>

Для отображения сообщений об ошибках, соответствующих myField, сначала создаём элемент с атрибутом ngMessages, установленным на объект $error, принадлежащий полю ввода myField в нашей форме myForm.

Затем внутри этого элемента мы создаём отдельные элементы для каждой из возможных ошибок, которые может содержать myField. Атрибут ngMessage используется для указания элементов, которые будут отображаться для каждой ошибки — например, установка ng-message="required" указывает, что этот конкретный элемент должен отображаться, когда для обязательного поля myField отсутствует значение (потому что ключ required будет true в объекте myForm.myField.$error).

Порядок сообщений

По умолчанию ngMessages будет отображать только одно сообщение для конкретной коллекции ключ/значение за раз. Если одновременно истинно более одного ключа сообщения (или ошибки), то какое сообщение отобразится, определяется порядком сообщений в коде шаблона HTML (сообщения, объявленные первыми, имеют приоритет). Этот механизм означает, что разработчик не должен назначать приоритеты сообщениям с помощью пользовательского кода JavaScript.

Учитывая следующий объект ошибок для нашего примера (который сообщает нам, что поле myField в настоящее время имеет ошибки required и email):

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

Пользователю будет отображено сообщение required, поскольку оно появляется перед сообщением email в DOM. Как только пользователь введёт один символ, сообщение required исчезнет (так как поле теперь имеет значение), но сообщение email останется видимым, поскольку оно всё ещё актуально.

Отображение нескольких сообщений одновременно

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

<!-- attribute-style usage -->
<div ng-messages="myForm.myField.$error" ng-messages-multiple>...</div>

<!-- element-style usage -->
<ng-messages for="myForm.myField.$error" multiple>...</ng-messages>

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

Помимо приоритизации, 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" role="alert">
  <div ng-messages-include="error-messages"></div>
</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">
  <label>
    Email address
    <input type="email"
           id="email"
           name="myEmail"
           ng-model="email"
           minlength="5"
           required />
  </label>
  <!-- any ng-message elements that appear BEFORE the ng-messages-include will
       override the messages present in the ng-messages-include template -->
  <div ng-messages="myForm.myEmail.$error" role="alert">
    <!-- 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>

    <!-- and here are the generic error messages -->
    <div ng-messages-include="my-custom-messages"></div>
  </div>
</form>

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

Динамические сообщения

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

<form name="myForm">
  <label>
    Email address
    <input type="email"
           name="myEmail"
           ng-model="email"
           minlength="5"
           required />
  </label>
  <div ng-messages="myForm.myEmail.$error" role="alert">
    <div ng-message="required">You did not enter your email address</div>
    <div ng-repeat="errorMessage in errorMessages">
      <!-- use ng-message-exp for a message whose key is given by an expression -->
      <div ng-message-exp="errorMessage.type">{{ errorMessage.text }}</div>
    </div>
  </div>
</form>

Выражение errorMessage.type может быть строковым значением или массивом, чтобы несколько ошибок можно было связать с одним сообщением об ошибке:

<label>
  Email address
  <input type="email"
         ng-model="data.email"
         name="myEmail"
         ng-minlength="5"
         ng-maxlength="100"
         required />
</label>
<div ng-messages="myForm.myEmail.$error" role="alert">
  <div ng-message-exp="'required'">You did not enter your email address</div>
  <div ng-message-exp="['minlength', 'maxlength']">
    Your email must be between 5 and 100 characters long
  </div>
</div>

Вы можете использовать другие структурные директивы, такие как ng-if и ng-switch, для дополнительного управления активными сообщениями и временем их активности. Будьте осторожны, если вы разместите ng-message на том же элементе, что и эти структурные директивы, Angular может не определить, активен ли какой-либо элемент, поэтому лучше поместить ng-message в дочерний элемент структурной директивы.

<div ng-messages="myForm.myEmail.$error" role="alert">
  <div ng-if="showRequiredError">
    <div ng-message="required">Please enter something</div>
  </div>
</div>

Анимации

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

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

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

<div ng-messages="myMessages" class="my-messages" role="alert">
  <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.