Улучшить эту документацию 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 будет отображать только одно сообщение для конкретной коллекции ключ/значение в любой момент времени. Если более чем один ключ сообщения (или ошибки) имеет значение true, то какое сообщение отображается, определяется порядком сообщений в 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 будут вызывать анимации всякий раз, когда 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 {}

См. документацию 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>