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

Установка

Сначала включите 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']);

С этим вы готовы начать!

Модуль 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 сообщение, установленное для required, переопределит соответствующее сообщение required, определённое в удалённом шаблоне. Таким образом, для конкретных полей ввода (например, адресов электронной почты, полей дат, полей автозаполнения и т.д.) можно применять специализированные сообщения об ошибках, одновременно используя более общие сообщения для обработки других, более общих ошибок ввода.

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

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.