iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

add files properly

This commit is contained in:
Alex Wolfe 2015-04-23 08:43:09 -07:00
parent ecc2afc10b
commit 3aadd7b76b
2 changed files with 658 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
public/docs/js/latest/api/annotations/Component-class.jade Normal file
View File

@ -0,0 +1,140 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations/annotations.js#L521">angular2/src/core/annotations/annotations.js (line 521)</a>
:markdown
Declare reusable UI building blocks for an application.
Each Angular component requires a single `@Component` and at least one `@View` annotation. The `@Component`
annotation specifies when a component is instantiated, and which properties and hostListeners it binds to.
When a component is instantiated, Angular
- creates a shadow DOM for the component.
- loads the selected template into the shadow DOM.
- creates a child <a href="../di/Injector-class.html"><code>Injector</code></a> which is configured with the `injectables` for the <a href="Component-class.html"><code>Component</code></a>.
All template expressions and statements are then evaluated against the component instance.
For details on the `@View` annotation, see <a href="View-class.html"><code>View</code></a>.
## Example
```
@Component({
selector: 'greet'
})
@View({
template: 'Hello {{name}}!'
})
class Greet {
name: string;
constructor() {
this.name = 'World';
}
}
```
.l-main-section
h2 Members
.l-sub-section
h3 constructor
pre.prettyprint
code.
constructor({
selector,
properties,
events,
hostListeners,
injectables,
lifecycle,
changeDetection = DEFAULT
}:{
selector:string,
properties:Object,
events:List,
hostListeners:Object,
injectables:List,
lifecycle:List,
changeDetection:string
}={})
:markdown
.l-sub-section
h3 changeDetection
:markdown
Defines the used change detection strategy.
When a component is instantiated, Angular creates a change detector, which is responsible for propagating
the component's bindings.
The `changeDetection` property defines, whether the change detection will be checked every time or only when the component
tells it to do so.
.l-sub-section
h3 injectables
:markdown
Defines the set of injectable objects that are visible to a Component and its children.
The `injectables` defined in the Component annotation allow you to configure a set of bindings for the component's
injector.
When a component is instantiated, Angular creates a new child Injector, which is configured with the bindings in
the Component `injectables` annotation. The injectable objects then become available for injection to the component
itself and any of the directives in the component's template, i.e. they are not available to the directives which
are children in the component's light DOM.
The syntax for configuring the `injectables` injectable is identical to <a href="../di/Injector-class.html"><code>Injector</code></a> injectable configuration.
See <a href="../di/Injector-class.html"><code>Injector</code></a> for additional detail.
## Simple Example
Here is an example of a class that can be injected:
```
class Greeter {
greet(name:string) {
return 'Hello ' + name + '!';
}
}
@Component({
selector: 'greet',
injectables: [
Greeter
]
})
@View({
template: `{{greeter.greet('world')}}!`,
directives: Child
})
class HelloWorld {
greeter:Greeter;
constructor(greeter:Greeter) {
this.greeter = greeter;
}
}
```

518
public/docs/js/latest/api/annotations/Directive-class.jade Normal file
View File

@ -0,0 +1,518 @@
p.location-badge.
exported from <a href="/angular2/annotations.html">angular2/annotations</a>
defined in <a href="https://github.com/angular/angular/tree/master/modules/angular2/src/core/annotations/annotations.js#L240">angular2/src/core/annotations/annotations.js (line 240)</a>
:markdown
Directives allow you to attach behavior to elements in the DOM.
Directive is an abstract concept, instead use concrete directives: <a href="Component-class.html"><code>Component</code></a>, <a href="DynamicComponent-class.html"><code>DynamicComponent</code></a>, <a href="Decorator-class.html"><code>Decorator</code></a>
or <a href="Viewport-class.html"><code>Viewport</code></a>.
A directive consists of a single directive annotation and a controller class. When the directive's `selector` matches
elements in the DOM, the following steps occur:
1. For each directive, the `ElementInjector` attempts to resolve the directive's constructor arguments.
2. Angular instantiates directives for each matched element using `ElementInjector` in a depth-first order,
as declared in the HTML.
## Understanding How Injection Works
There are three stages of injection resolution.
- *Pre-existing Injectors*:
- The terminal <a href="../di/Injector-class.html"><code>Injector</code></a> cannot resolve dependencies. It either throws an error or, if the dependency was
specified as `@Optional`, returns `null`.
- The platform injector resolves browser singleton resources, such as: cookies, title, location, and others.
- *Component Injectors*: Each `@Component` has its own <a href="../di/Injector-class.html"><code>Injector</code></a>, and they follow the same parent-child hierarchy
as the components in the DOM.
- *Element Injectors*: Each component has a Shadow DOM. Within the Shadow DOM each element has an `ElementInjector`
which follow the same parent-child hierarchy as the DOM elements themselves.
When a template is instantiated, it also must instantiate the corresponding directives in a depth-first order. The
current `ElementInjector` resolves the constructor dependencies for each directive.
Angular then resolves dependencies as follows, according to the order in which they appear in the <a href="View-class.html"><code>View</code></a>:
1. Dependencies on the current element
2. Dependencies on element injectors and their parents until it encounters a Shadow DOM boundary
3. Dependencies on component injectors and their parents until it encounters the root component
4. Dependencies on pre-existing injectors
The `ElementInjector` can inject other directives, element-specific special objects, or it can delegate to the parent
injector.
To inject other directives, declare the constructor parameter as:
- `directive:DirectiveType`: a directive on the current element only
- `@Ancestor() directive:DirectiveType`: any directive that matches the type between the current element and the
Shadow DOM root. Current element is not included in the resolution, therefore even if it could resolve it, it will
be ignored.
- `@Parent() directive:DirectiveType`: any directive that matches the type on a direct parent element only.
- `@Children query:Query<DirectiveType>`: A live collection of direct child directives (will be implemented in later release).
- `@Descendants query:Query<DirectiveType>`: A live collection of any child directives (will be implemented in later relaese).
To inject element-specific special objects, declare the constructor parameter as:
- `element: NgElement` to obtain a DOM element (DEPRECATED: replacement coming)
- `viewContainer: ViewContainer` to control child template instantiation, for <a href="Viewport-class.html"><code>Viewport</code></a> directives only
- `bindingPropagation: BindingPropagation` to control change detection in a more granular way.
## Example
The following example demonstrates how dependency injection resolves constructor arguments in practice.
Assume this HTML template:
```
<div dependency="1">
<div dependency="2">
<div dependency="3" my-directive>
<div dependency="4">
<div dependency="5"></div>
</div>
<div dependency="6"></div>
</div>
</div>
</div>
```
With the following `dependency` decorator and `SomeService` injectable class.
```
@Injectable()
class SomeService {
}
@Decorator({
selector: '[dependency]',
properties: {
'id':'dependency'
}
})
class Dependency {
id:string;
}
```
Let's step through the different ways in which `MyDirective` could be declared...
### No injection
Here the constructor is declared with no arguments, therefore nothing is injected into `MyDirective`.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor() {
}
}
```
This directive would be instantiated with no dependencies.
### Component-level injection
Directives can inject any injectable instance from the closest component injector or any of its parents.
Here, the constructor declares a parameter, `someService`, and injects the `SomeService` type from the parent
component's injector.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor(someService: SomeService) {
}
}
```
This directive would be instantiated with a dependency on `SomeService`.
### Injecting a directive from the current element
Directives can inject other directives declared on the current element.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor(dependency: Dependency) {
expect(dependency.id).toEqual(3);
}
}
```
This directive would be instantiated with `Dependency` declared at the same element, in this case `dependency="3"`.
### Injecting a directive from a direct parent element
Directives can inject other directives declared on a direct parent element. By definition, a directive with a
`@Parent` annotation does not attempt to resolve dependencies for the current element, even if this would satisfy
the dependency.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor(@Parent() dependency: Dependency) {
expect(dependency.id).toEqual(2);
}
}
```
This directive would be instantiated with `Dependency` declared at the parent element, in this case `dependency="2"`.
### Injecting a directive from any ancestor elements
Directives can inject other directives declared on any ancestor element (in the current Shadow DOM), i.e. on the
parent element and its parents. By definition, a directive with an `@Ancestor` annotation does not attempt to
resolve dependencies for the current element, even if this would satisfy the dependency.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor(@Ancestor() dependency: Dependency) {
expect(dependency.id).toEqual(2);
}
}
```
Unlike the `@Parent` which only checks the parent, `@Ancestor` checks the parent, as well as its
parents recursively. If `dependency="2"` didn't exist on the direct parent, this injection would have returned
`dependency="1"`.
### Injecting a live collection of direct child directives
A directive can also query for other child directives. Since parent directives are instantiated before child
directives, a directive can't simply inject the list of child directives. Instead, the directive
injects a <a href="../view/QueryList-class.html"><code>QueryList</code></a>, which updates its contents as children are added, removed, or moved by any
<a href="Viewport-class.html"><code>Viewport</code></a> directive such as a `for`, an `if`, or a `switch`.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor(@Query(Marker) dependencies:QueryList<Maker>) {
}
}
```
This directive would be instantiated with a <a href="../view/QueryList-class.html"><code>QueryList</code></a> which contains `Dependency` 4 and 6. Here, `Dependency`
5 would not be included, because it is not a direct child.
### Injecting a live collection of descendant directives
Note: This is will be implemented in later release. ()
Similar to `@Children` above, but also includes the children of the child elements.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor(@QueryDescendents(Marker) dependencies:QueryList<Maker>) {
}
}
```
This directive would be instantiated with a Query which would contain `Dependency` 4, 5 and 6.
### Optional injection
The normal behavior of directives is to return an error when a specified dependency cannot be resolved. If you
would like to inject `null` on unresolved dependency instead, you can annotate that dependency with `@Optional()`.
This explicitly permits the author of a template to treat some of the surrounding directives as optional.
```
@Decorator({ selector: '[my-directive]' })
class MyDirective {
constructor(@Optional() dependency:Dependency) {
}
}
```
This directive would be instantiated with a `Dependency` directive found on the current element. If none can be
found, the injector supplies `null` instead of throwing an error.
.l-main-section
h2 Members
.l-sub-section
h3 constructor
pre.prettyprint
code.
constructor({
selector,
properties,
events,
hostListeners,
lifecycle
}:{
selector:string,
properties:any,
events:List,
hostListeners: any,
lifecycle:List
}={})
:markdown
.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');
}
}
```
.l-sub-section
h3 hasLifecycleHook
pre.prettyprint
code.
hasLifecycleHook(hook:string)
:markdown
Returns true if a directive participates in a given `LifecycleEvent`.
See <a href="onChange-var.html"><code>onChange</code></a>, <a href="onDestroy-var.html"><code>onDestroy</code></a>, <a href="onAllChangesDone-var.html"><code>onAllChangesDone</code></a> for details.
.l-sub-section
h3 hostListeners
:markdown
Specifies which DOM hostListeners a directive listens to.
The `hostListeners` property defines 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({
hostListeners: {
'event1': 'onMethod1(arguments)',
'target:event2': 'onMethod2(arguments)',
...
}
}
```
## Basic Event Binding:
Suppose you want to write a directive that triggers on `change` events in the DOM and on `resize` events in window.
You would define the event binding as follows:
```
@Decorator({
selector: 'input',
hostListeners: {
'change': 'onChange($event)',
'window:resize': 'onResize($event)'
}
})
class InputDecorator {
onChange(event:Event) {
}
onResize(event:Event) {
}
}
```
Here the `onChange` method of `InputDecorator` is invoked whenever the DOM element fires the 'change' event.
.l-sub-section
h3 lifecycle
:markdown
Specifies a set of lifecycle hostListeners in which the directive participates.
See <a href="onChange-var.html"><code>onChange</code></a>, <a href="onDestroy-var.html"><code>onDestroy</code></a>, <a href="onAllChangesDone-var.html"><code>onAllChangesDone</code></a> for details.
.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`
key-value pairs:
- `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="../pipes/Pipe-class.html"><code>Pipe</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
```
@Directive({
properties: {
'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:
```
@Decorator({
selector: '[tooltip]',
properties: {
'text': 'tooltip'
}
})
class Tooltip {
set text(text) {
// This will get called every time the 'tooltip' binding changes with the new value.
}
}
```
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 also use pipes when writing binding definitions for a directive.
For example, we could write a binding that updates the directive on structural changes, rather than on reference
changes, as normally occurs in change detection.
See <a href="../pipes/Pipe-class.html"><code>Pipe</code></a> and <a href="../pipes/keyValDiff-var.html"><code>keyValDiff</code></a> documentation for more details.
```
@Decorator({
selector: '[class-set]',
properties: {
'classChanges': 'classSet | keyValDiff'
}
})
class ClassSet {
set classChanges(changes:KeyValueChanges) {
// This will get called every time the `class-set` expressions changes its structure.
}
}
```
The template that this directive is used in may also contain its own pipes. For example:
```html
<div [class-set]="someExpression | somePipe">
```
In this case, the two pipes compose as if they were inlined: `someExpression | somePipe | keyValDiff`.
.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.