AngularJS: API: ngMessages

`ngMessages`

ThengMessagesmodule provides enhanced support for displaying messages within templates (typically within forms or when rendering message objects that return key/value data). Instead of relying on JavaScript code and/or complex ng-if statements within your form template to show and hide error messages specific to the state of an input field, thengMessagesandngMessagedirectives are designed to handle the complexity, inheritance and priority sequencing based on the order of how the messages are defined in the template.

Currently, the ngMessages module only contains the code for thengMessagesandngMessagedirectives.

用法

ThengMessagesdirective listens on a key/value collection which is set on the ngMessages attribute. Since the ngModel directive exposes an$errorobject, this error object can be used withngMessagesto display control error messages in an easier way than with just regular angular template directives.

name="myForm">Type="text"ng-model="field"name="myField"requiredminlength="5"/>ng-messages="myForm.myField.$error">ng-message="required">You did not enter a field

ng-message="minlength">The value entered is too short

Now whatever key/value entries are present within the provided object (in this case$error) then the ngMessages directive will render the inner first ngMessage directive (depending if the key values match the attribute value present on each ngMessage directive). In other words, if your errors object contains the following data:

myField.$error = { minlength : true, required : false };

Then therequiredmessage will be displayed first. When required is false then theminlengthmessage will be displayed right after (since these messages are ordered this way in the template HTML code). The prioritization of each message is determined by what order they're present in the DOM. Therefore, instead of having custom JavaScript code determine the priority of what errors are present before others, the presentation of the errors are handled within the template.

默认情况下， ngMessages will only display one error at a time. However, if you wish to display all messages then theng-messages-multipleattribute flag can be used on the element containing the ngMessages directive to make this happen.

ng-messages="myForm.myField.$error"ng-messages-multiple>...

Reusing and Overriding Messages

In addition to prioritization, ngMessages also allows for including messages from a remote or an inline template. This allows for generic collection of messages to be reused across multiple parts of an application.

Type="text/ng-template"id="error-messages"><div ng-message="required">Thisfield is required</div> This field is too shortdiv>ng-messages="myForm.myField.$error"ng-messages-include="error-messages">

However, including generic messages may not be useful enough to match all input fields, therefore,ngMessagesprovides the ability to override messages defined in the remote template by redefining then within the directive container.

Type="text/ng-template"id="my-custom-messages"><div ng-message="required">Thisfield is required</div> This field is too shortdiv>name="myForm">Type="email"id="email"name="myEmail"ng-model="email"minlength="5"required/>ng-messages="myForm.myEmail.$error"ng-messages-include="my-custom-messages">ng-message="required">You did not enter your email addressng-message="email">Your email address is invalid

In the example HTML code above the message that is set on required will override the corresponding required message defined within the remote template. Therefore, with particular input fields (such email addresses, date fields, autocomplete inputs, etc...), specialized error messages can be applied while more generic messages can be used to handle other, more general input errors.

动画

If thengAnimatemodule is active within the application then both thengMessagesandngMessagedirectives will trigger animations whenever any messages are added and removed from the DOM by thengMessagesdirective.

Whenever thengMessagesdirective contains one or more visible messages then the.ng-activeCSS class will be added to the element. The.ng-inactiveCSS class will be applied when there are no animations present. Therefore, CSS transitions and keyframes as well as JavaScript animations can hook into the animations whenever these classes are added/removed.

Let's say that our HTML code for our messages container looks like so:

ng-messages="myMessages"class="my-messages">ng-message="alert"class="some-message">...

ng-message="fail"class="some-message">...

Then the CSS animation code for the message container looks like so:

.my-messages{transition:1slinear all;}.my-messages.ng-active{//messages are visible}.my-messages.ng-inactive{//messages are hidden}

Whenever an inner message is attached (becomes visible) or removed (becomes hidden) then the enter and leave animation is triggered for each particular element bound to thengMessagedirective.

Therefore, the CSS code for the inner messages looks like so:

.some-message{transition:1slinear all;}.some-message.ng-enter{}.some-message.ng-enter.ng-enter-active{}.some-message.ng-leave{}.some-message.ng-leave.ng-leave-active{}

点击这里 to learn how to use JavaScript animations or to learn more about ngAnimate.

Installation

First includeangular-messages.jsin your HTML:

src="angular.js">src="angular-messages.js">

You can download this file from the following places:

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"

where X.Y.Z is the AngularJS version you are running.

Then load the module in your application by adding it as a dependent module:

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

With that you're ready to get started!

模块组件

Directive

名称	描述
ngMessages	`ngMessages`is a directive that is designed to show and hide messages based on the state of a key/value object that it listens on. The directive itself compliments error message reporting with the`ngModel`$error object (which stores a key/value state of validation errors).
ngMessage	`ngMessage`is a directive with the purpose to show and hide a particular message. For`ngMessage`to operate, a parent`ngMessages`directive on a parent DOM element must be situated since it determines which messages are visible based on the state of the provided key/value map that`ngMessages`listens on.