Улучшить эту документацию 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 и ngMessageDefault.

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

Директива 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 и %%%CODE_BLOCK_45%%):

<!-- 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 будут запускать анимации всякий раз, когда директива ngMessages добавляет и удаляет сообщения из DOM.

Всякий раз, когда директива ngMessages содержит одно или несколько видимых сообщений, к элементу будет добавлен класс .ng-active CSS. Класс .ng-inactive CSS будет применяться, когда сообщений нет. Таким образом, 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 {}

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

Отображение сообщения по умолчанию

Если ngMessages не отображает ни одной внутренней директивы ngMessage (т. е. когда ни один из истинностных ключей не соответствует определенному сообщению), он отобразит сообщение по умолчанию с помощью директивы ngMessageDefault. Обратите внимание, что соответствующие сообщения всегда имеют приоритет над несоответствующими сообщениями. Это означает, что сообщение по умолчанию не будет отображаться, когда будет соответствовать другое сообщение. Это также верно для ng-messages-multiple.

<div ng-messages="myForm.myField.$error" role="alert">
  <div ng-message="required">This field is required</div>
  <div ng-message="minlength">This field is too short</div>
  <div ng-message-default>This field has an input error</div>
</div>