angular-cn/public/docs/js/latest/api/metadata/DirectiveMetadata-class.jade

433 lines
10 KiB
Plaintext

p.location-badge.
exported from <a href='../metadata'>angular2/metadata</a>
defined in <a href="https://github.com/angular/angular/tree/2.0.0-alpha.36/modules/angular2/src/core/metadata/directives.ts#L3-L728">angular2/src/core/metadata/directives.ts (line 3)</a>
:markdown
Annotations provide the additional information that Angular requires in order to run your
application. This module
contains <a href='ComponentMetadata-class.html'><code>ComponentMetadata</code></a>, <a href='DirectiveMetadata-class.html'><code>DirectiveMetadata</code></a>, and <a href='ViewMetadata-class.html'><code>ViewMetadata</code></a>
annotations, as well as
the <a href='../di/Host-var.html'><code>Host</code></a> annotation that is used by Angular to resolve dependencies.
.l-main-section
h2 Annotations
.l-sub-section
h3.annotation CONST
pre.prettyprint
code.
@CONST()
.l-main-section
h2 Members
.l-sub-section
h3 constructor
pre.prettyprint
code.
constructor({
selector, properties, events, host, lifecycle, bindings, exportAs,
compileChildren = true,
}?: {
selector?: string,
properties?: string[],
events?: string[],
host?: StringMap&lt;string, string&gt;,
lifecycle?: LifecycleEvent[],
bindings?: any[],
exportAs?: string,
compileChildren?: boolean,
})
:markdown
.l-sub-section
h3 selector
:markdown
The CSS selector that triggers the instantiation of a directive.
Angular only allows directives to trigger on CSS selectors that do not cross element
boundaries.
`selector` may be declared as one of the following:
- `element-name`: select by element name.
- `.class`: select by class name.
- `[attribute]`: select by attribute name.
- `[attribute=value]`: select by attribute name and value.
- `:not(sub_selector)`: select only if the element does not match the `sub_selector`.
- `selector1, selector2`: select if either `selector1` or `selector2` matches.
Suppose we have a directive with an `input[type=text]` selector.
And the following HTML:
```html
<form>
<input type="text">
<input type="radio">
<form>
```
The directive would only be instantiated on the `<input type="text">` element.
.l-sub-section
h3 properties
:markdown
Enumerates the set of properties that accept data binding for a directive.
The `properties` property defines a set of `directiveProperty` to `bindingProperty`
configuration:
- `directiveProperty` specifies the component property where the value is written.
- `bindingProperty` specifies the DOM property where the value is read from.
You can include a <a href='PipeMetadata-class.html'><code>PipeMetadata</code></a> when specifying a `bindingProperty` to allow for data
transformation and structural change detection of the value. These pipes will be evaluated in
the context of this component.
## Syntax
There is no need to specify both `directiveProperty` and `bindingProperty` when they both have
the same value.
```
@Directive({
properties: [
'propertyName', // shorthand notation for 'propertyName: propertyName'
'directiveProperty1: bindingProperty1',
'directiveProperty2: bindingProperty2 | pipe1 | ...',
...
]
}
```
## Basic Property Binding
We can easily build a simple `Tooltip` directive that exposes a `tooltip` property, which can
be used in templates with standard Angular syntax. For example:
```
@Directive({
selector: '[tooltip]',
properties: [
'text: tooltip'
]
})
class Tooltip {
set text(value: string) {
// This will get called every time with the new value when the 'tooltip' property changes
}
}
```
We can then bind to the `tooltip' property as either an expression (`someExpression`) or as a
string literal, as shown in the HTML template below:
```html
<div [tooltip]="someExpression">...</div>
<div tooltip="Some Text">...</div>
```
Whenever the `someExpression` expression changes, the `properties` declaration instructs
Angular to update the `Tooltip`'s `text` property.
### Bindings With Pipes
You can use pipes in bindings, as follows:
```html
<div [class-set]="someExpression | somePipe">
```
.l-sub-section
h3 events
:markdown
Enumerates the set of emitted events.
## Syntax
```
@Component({
events: ['statusChange']
})
class TaskComponent {
statusChange: EventEmitter;
constructor() {
this.statusChange = new EventEmitter();
}
onComplete() {
this.statusChange.next('completed');
}
}
```
Use `propertyName: eventName` when the event emitter property name is different from the name
of the emitted event:
```
@Component({
events: ['status: statusChange']
})
class TaskComponent {
status: EventEmitter;
constructor() {
this.status = new EventEmitter();
}
onComplete() {
this.status.next('completed');
}
}
```
.l-sub-section
h3 host
:markdown
Specifiy the events, actions, properties and attributes related to the host element.
## Events
Specifies which DOM hostListeners a directive listens to via a set of `(event)` to `method`
key-value pairs:
- `event1`: the DOM event that the directive listens to.
- `statement`: the statement to execute when the event occurs.
If the evalutation of the statement returns `false`, then `preventDefault`is applied on the DOM
event.
To listen to global events, a target must be added to the event name.
The target can be `window`, `document` or `body`.
When writing a directive event binding, you can also refer to the following local variables:
- `$event`: Current event object which triggered the event.
- `$target`: The source of the event. This will be either a DOM element or an Angular
directive. (will be implemented in later release)
## Syntax
```
@Directive({
host: {
'(event1)': 'onMethod1(arguments)',
'(target:event2)': 'onMethod2(arguments)',
...
}
}
```
## Basic Event Binding:
Suppose you want to write a directive that reacts to `change` events in the DOM and on
`resize` events in window.
You would define the event binding as follows:
```
@Directive({
selector: 'input',
host: {
'(change)': 'onChange($event)',
'(window:resize)': 'onResize($event)'
}
})
class InputDirective {
onChange(event:Event) {
// invoked when the input element fires the 'change' event
}
onResize(event:Event) {
// invoked when the window fires the 'resize' event
}
}
```
## Properties
Specifies which DOM properties a directives updates.
## Syntax
```
@Directive({
selector: 'input',
host: {
'[prop]': 'expression'
}
})
class InputDirective {
value:string;
}
```
In this example the prop property of the host element is updated with the expression value
every time it changes.
## Attributes
Specifies static attributes that should be propagated to a host element. Attributes specified
in `hostAttributes` are propagated only if a given attribute is not present on a host element.
## Syntax
```
@Directive({
selector: '[my-button]',
host: {
'role': 'button'
}
})
class MyButton {
}
```
In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
(here: `<div>` ) will ensure that this element will get the "button" role.
.l-sub-section
h3 lifecycle
:markdown
Specifies which lifecycle should be notified to the directive.
See <a href='LifecycleEvent-enum.html'><code>LifecycleEvent</code></a> for details.
.l-sub-section
h3 compileChildren
:markdown
If set to false the compiler does not compile the children of this directive.
.l-sub-section
h3 bindings
:markdown
Defines the set of injectable objects that are visible to a Directive and its light dom
children.
## Simple Example
Here is an example of a class that can be injected:
```
class Greeter {
greet(name:string) {
return 'Hello ' + name + '!';
}
}
@Directive({
selector: 'greet',
bindings: [
Greeter
]
})
class HelloWorld {
greeter:Greeter;
constructor(greeter:Greeter) {
this.greeter = greeter;
}
}
```
.l-sub-section
h3 exportAs
:markdown
Defines the name that can be used in the template to assign this directive to a variable.
## Simple Example
```
@Directive({
selector: 'child-dir',
exportAs: 'child'
})
class ChildDir {
}
@Component({
selector: 'main',
})
@View({
template: `<child-dir #c="child"></child-dir>`,
directives: [ChildDir]
})
class MainComponent {
}
```