Улучшить эту документацию 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 на тот же элемент, что и эти структурные директивы, AngularJS может не определить, активно ли сообщение. Поэтому лучше размещать 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 будут вызывать анимации всякий раз, когда любые сообщения добавляются и удаляются из DOM директивой ngMessages.

Всякий раз, когда директива 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.