433 lines
10 KiB
Plaintext
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<string, string>,
|
|
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 {
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|