chore(docs): copy [Decorator]Metadata docs to the [Decorator]
This allows editors to show the docs when users navigate to definition. See #4668 Closes #4683
This commit is contained in:
Alex Eagle
Alex Eagle
parent
1aeafd31bd
commit
947bf11cb6
|
|
@ -505,82 +505,915 @@ export interface HostListenerFactory {
|
|||
new (eventName: string, args?: string[]): any;
|
||||
}
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from ComponentMetadata.
|
||||
/**
|
||||
* {@link ComponentMetadata} factory function.
|
||||
* 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 all the injectable objects configured with `providers` and `viewProviders`.
|
||||
*
|
||||
* All template expressions and statements are then evaluated against the component instance.
|
||||
*
|
||||
* For details on the `@View` annotation, see {@link ViewMetadata}.
|
||||
*
|
||||
* ## Lifecycle hooks
|
||||
*
|
||||
* When the component class implements some {@link angular2/lifecycle_hooks} the callbacks are
|
||||
* called by the change detection at defined points in time during the life of the component.
|
||||
*
|
||||
* ## Example
|
||||
*
|
||||
* ```
|
||||
* @Component({
|
||||
* selector: 'greet',
|
||||
* template: 'Hello {{name}}!'
|
||||
* })
|
||||
* class Greet {
|
||||
* name: string;
|
||||
*
|
||||
* constructor() {
|
||||
* this.name = 'World';
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
*/
|
||||
export var Component: ComponentFactory =
|
||||
<ComponentFactory>makeDecorator(ComponentMetadata, (fn: any) => fn.View = View);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from DirectiveMetadata.
|
||||
/**
|
||||
* {@link DirectiveMetadata} factory function.
|
||||
* Directives allow you to attach behavior to elements in the DOM.
|
||||
*
|
||||
* {@link DirectiveMetadata}s with an embedded view are called {@link ComponentMetadata}s.
|
||||
*
|
||||
* 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 {@link Injector} 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 instance has its own {@link Injector}, and they follow
|
||||
* the same parent-child hierarchy
|
||||
* as the component instances in the DOM.
|
||||
* - *Element Injectors*: Each component instance 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
|
||||
* {@link ViewMetadata}:
|
||||
*
|
||||
* 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
|
||||
* - `@Host() directive:DirectiveType`: any directive that matches the type between the current
|
||||
* element and the
|
||||
* Shadow DOM root.
|
||||
* - `@Query(DirectiveType) query:QueryList<DirectiveType>`: A live collection of direct child
|
||||
* directives.
|
||||
* - `@QueryDescendants(DirectiveType) query:QueryList<DirectiveType>`: A live collection of any
|
||||
* child directives.
|
||||
*
|
||||
* To inject element-specific special objects, declare the constructor parameter as:
|
||||
* - `element: ElementRef` to obtain a reference to logical element in the view.
|
||||
* - `viewContainer: ViewContainerRef` to control child template instantiation, for
|
||||
* {@link DirectiveMetadata} 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 {
|
||||
* }
|
||||
*
|
||||
* @Directive({
|
||||
* selector: '[dependency]',
|
||||
* inputs: [
|
||||
* '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`.
|
||||
*
|
||||
* ```
|
||||
* @Directive({ 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.
|
||||
* ```
|
||||
* @Directive({ 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.
|
||||
*
|
||||
* ```
|
||||
* @Directive({ 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 any ancestor elements
|
||||
*
|
||||
* Directives can inject other directives declared on any ancestor element (in the current Shadow
|
||||
* DOM), i.e. on the current element, the
|
||||
* parent element, or its parents.
|
||||
* ```
|
||||
* @Directive({ selector: '[my-directive]' })
|
||||
* class MyDirective {
|
||||
* constructor(@Host() dependency: Dependency) {
|
||||
* expect(dependency.id).toEqual(2);
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* `@Host` checks the current element, 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 {@link QueryList}, which updates its contents as children are added,
|
||||
* removed, or moved by a directive that uses a {@link ViewContainerRef} such as a `ng-for`, an
|
||||
* `ng-if`, or an `ng-switch`.
|
||||
*
|
||||
* ```
|
||||
* @Directive({ selector: '[my-directive]' })
|
||||
* class MyDirective {
|
||||
* constructor(@Query(Dependency) dependencies:QueryList<Dependency>) {
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* This directive would be instantiated with a {@link QueryList} 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
|
||||
*
|
||||
* By passing the descendant flag to `@Query` above, we can include the children of the child
|
||||
* elements.
|
||||
*
|
||||
* ```
|
||||
* @Directive({ selector: '[my-directive]' })
|
||||
* class MyDirective {
|
||||
* constructor(@Query(Dependency, {descendants: true}) dependencies:QueryList<Dependency>) {
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* ```
|
||||
* @Directive({ 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.
|
||||
*
|
||||
* ## Example
|
||||
*
|
||||
* Here we use a decorator directive to simply define basic tool-tip behavior.
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: '[tooltip]',
|
||||
* inputs: [
|
||||
* 'text: tooltip'
|
||||
* ],
|
||||
* host: {
|
||||
* '(mouseenter)': 'onMouseEnter()',
|
||||
* '(mouseleave)': 'onMouseLeave()'
|
||||
* }
|
||||
* })
|
||||
* class Tooltip{
|
||||
* text:string;
|
||||
* overlay:Overlay; // NOT YET IMPLEMENTED
|
||||
* overlayManager:OverlayManager; // NOT YET IMPLEMENTED
|
||||
*
|
||||
* constructor(overlayManager:OverlayManager) {
|
||||
* this.overlay = overlay;
|
||||
* }
|
||||
*
|
||||
* onMouseEnter() {
|
||||
* // exact signature to be determined
|
||||
* this.overlay = this.overlayManager.open(text, ...);
|
||||
* }
|
||||
*
|
||||
* onMouseLeave() {
|
||||
* this.overlay.close();
|
||||
* this.overlay = null;
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
* In our HTML template, we can then add this behavior to a `<div>` or any other element with the
|
||||
* `tooltip` selector,
|
||||
* like so:
|
||||
*
|
||||
* ```
|
||||
* <div tooltip="some text here"></div>
|
||||
* ```
|
||||
*
|
||||
* Directives can also control the instantiation, destruction, and positioning of inline template
|
||||
* elements:
|
||||
*
|
||||
* A directive uses a {@link ViewContainerRef} to instantiate, insert, move, and destroy views at
|
||||
* runtime.
|
||||
* The {@link ViewContainerRef} is created as a result of `<template>` element, and represents a
|
||||
* location in the current view
|
||||
* where these actions are performed.
|
||||
*
|
||||
* Views are always created as children of the current {@link ViewMetadata}, and as siblings of the
|
||||
* `<template>` element. Thus a
|
||||
* directive in a child view cannot inject the directive that created it.
|
||||
*
|
||||
* Since directives that create views via ViewContainers are common in Angular, and using the full
|
||||
* `<template>` element syntax is wordy, Angular
|
||||
* also supports a shorthand notation: `<li *foo="bar">` and `<li template="foo: bar">` are
|
||||
* equivalent.
|
||||
*
|
||||
* Thus,
|
||||
*
|
||||
* ```
|
||||
* <ul>
|
||||
* <li *foo="bar" title="text"></li>
|
||||
* </ul>
|
||||
* ```
|
||||
*
|
||||
* Expands in use to:
|
||||
*
|
||||
* ```
|
||||
* <ul>
|
||||
* <template [foo]="bar">
|
||||
* <li title="text"></li>
|
||||
* </template>
|
||||
* </ul>
|
||||
* ```
|
||||
*
|
||||
* Notice that although the shorthand places `*foo="bar"` within the `<li>` element, the binding for
|
||||
* the directive
|
||||
* controller is correctly instantiated on the `<template>` element rather than the `<li>` element.
|
||||
*
|
||||
* ## Lifecycle hooks
|
||||
*
|
||||
* When the directive class implements some {@link angular2/lifecycle_hooks} the callbacks are
|
||||
* called by the change detection at defined points in time during the life of the directive.
|
||||
*
|
||||
* ## Example
|
||||
*
|
||||
* Let's suppose we want to implement the `unless` behavior, to conditionally include a template.
|
||||
*
|
||||
* Here is a simple directive that triggers on an `unless` selector:
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: '[unless]',
|
||||
* inputs: ['unless']
|
||||
* })
|
||||
* export class Unless {
|
||||
* viewContainer: ViewContainerRef;
|
||||
* templateRef: TemplateRef;
|
||||
* prevCondition: boolean;
|
||||
*
|
||||
* constructor(viewContainer: ViewContainerRef, templateRef: TemplateRef) {
|
||||
* this.viewContainer = viewContainer;
|
||||
* this.templateRef = templateRef;
|
||||
* this.prevCondition = null;
|
||||
* }
|
||||
*
|
||||
* set unless(newCondition) {
|
||||
* if (newCondition && (isBlank(this.prevCondition) || !this.prevCondition)) {
|
||||
* this.prevCondition = true;
|
||||
* this.viewContainer.clear();
|
||||
* } else if (!newCondition && (isBlank(this.prevCondition) || this.prevCondition)) {
|
||||
* this.prevCondition = false;
|
||||
* this.viewContainer.create(this.templateRef);
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* We can then use this `unless` selector in a template:
|
||||
* ```
|
||||
* <ul>
|
||||
* <li *unless="expr"></li>
|
||||
* </ul>
|
||||
* ```
|
||||
*
|
||||
* Once the directive instantiates the child view, the shorthand notation for the template expands
|
||||
* and the result is:
|
||||
*
|
||||
* ```
|
||||
* <ul>
|
||||
* <template [unless]="exp">
|
||||
* <li></li>
|
||||
* </template>
|
||||
* <li></li>
|
||||
* </ul>
|
||||
* ```
|
||||
*
|
||||
* Note also that although the `<li></li>` template still exists inside the `<template></template>`,
|
||||
* the instantiated
|
||||
* view occurs on the second `<li></li>` which is a sibling to the `<template>` element.
|
||||
*/
|
||||
export var Directive: DirectiveFactory = <DirectiveFactory>makeDecorator(DirectiveMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewMetadata.
|
||||
/**
|
||||
* {@link ViewMetadata} factory function.
|
||||
* Metadata properties available for configuring Views.
|
||||
*
|
||||
* Each Angular component requires a single `@Component` and at least one `@View` annotation. The
|
||||
* `@View` annotation specifies the HTML template to use, and lists the directives that are active
|
||||
* within the template.
|
||||
*
|
||||
* When a component is instantiated, the template is loaded into the component's shadow root, and
|
||||
* the expressions and statements in the template are evaluated against the component.
|
||||
*
|
||||
* For details on the `@Component` annotation, see {@link ComponentMetadata}.
|
||||
*
|
||||
* ## Example
|
||||
*
|
||||
* ```
|
||||
* @Component({
|
||||
* selector: 'greet',
|
||||
* template: 'Hello {{name}}!',
|
||||
* directives: [GreetUser, Bold]
|
||||
* })
|
||||
* class Greet {
|
||||
* name: string;
|
||||
*
|
||||
* constructor() {
|
||||
* this.name = 'World';
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export var View: ViewFactory =
|
||||
<ViewFactory>makeDecorator(ViewMetadata, (fn: any) => fn.View = View);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from AttributeMetadata.
|
||||
/**
|
||||
* {@link AttributeMetadata} factory function.
|
||||
* Metadata properties available for configuring Views.
|
||||
*
|
||||
* Each Angular component requires a single `@Component` and at least one `@View` annotation. The
|
||||
* `@View` annotation specifies the HTML template to use, and lists the directives that are active
|
||||
* within the template.
|
||||
*
|
||||
* When a component is instantiated, the template is loaded into the component's shadow root, and
|
||||
* the expressions and statements in the template are evaluated against the component.
|
||||
*
|
||||
* For details on the `@Component` annotation, see {@link ComponentMetadata}.
|
||||
*
|
||||
* ## Example
|
||||
*
|
||||
* ```
|
||||
* @Component({
|
||||
* selector: 'greet',
|
||||
* template: 'Hello {{name}}!',
|
||||
* directives: [GreetUser, Bold]
|
||||
* })
|
||||
* class Greet {
|
||||
* name: string;
|
||||
*
|
||||
* constructor() {
|
||||
* this.name = 'World';
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export var Attribute: AttributeFactory = makeParamDecorator(AttributeMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from QueryMetadata.
|
||||
/**
|
||||
* {@link QueryMetadata} factory function.
|
||||
* Declares an injectable parameter to be a live list of directives or variable
|
||||
* bindings from the content children of a directive.
|
||||
*
|
||||
* ### Example ([live demo](http://plnkr.co/edit/lY9m8HLy7z06vDoUaSN2?p=preview))
|
||||
*
|
||||
* Assume that `<tabs>` component would like to get a list its children `<pane>`
|
||||
* components as shown in this example:
|
||||
*
|
||||
* ```html
|
||||
* <tabs>
|
||||
* <pane title="Overview">...</pane>
|
||||
* <pane *ng-for="#o of objects" [title]="o.title">{{o.text}}</pane>
|
||||
* </tabs>
|
||||
* ```
|
||||
*
|
||||
* The preferred solution is to query for `Pane` directives using this decorator.
|
||||
*
|
||||
* ```javascript
|
||||
* @Component({
|
||||
* selector: 'pane',
|
||||
* inputs: ['title']
|
||||
* })
|
||||
* class Pane {
|
||||
* title:string;
|
||||
* }
|
||||
*
|
||||
* @Component({
|
||||
* selector: 'tabs',
|
||||
* template: `
|
||||
* <ul>
|
||||
* <li *ng-for="#pane of panes">{{pane.title}}</li>
|
||||
* </ul>
|
||||
* <content></content>
|
||||
* `
|
||||
* })
|
||||
* class Tabs {
|
||||
* panes: QueryList<Pane>;
|
||||
* constructor(@Query(Pane) panes:QueryList<Pane>) {
|
||||
* this.panes = panes;
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* A query can look for variable bindings by passing in a string with desired binding symbol.
|
||||
*
|
||||
* ### Example ([live demo](http://plnkr.co/edit/sT2j25cH1dURAyBRCKx1?p=preview))
|
||||
* ```html
|
||||
* <seeker>
|
||||
* <div #findme>...</div>
|
||||
* </seeker>
|
||||
*
|
||||
* @Component({ selector: 'foo' })
|
||||
* class seeker {
|
||||
* constructor(@Query('findme') elList: QueryList<ElementRef>) {...}
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* In this case the object that is injected depend on the type of the variable
|
||||
* binding. It can be an ElementRef, a directive or a component.
|
||||
*
|
||||
* Passing in a comma separated list of variable bindings will query for all of them.
|
||||
*
|
||||
* ```html
|
||||
* <seeker>
|
||||
* <div #find-me>...</div>
|
||||
* <div #find-me-too>...</div>
|
||||
* </seeker>
|
||||
*
|
||||
* @Component({
|
||||
* selector: 'foo'
|
||||
* })
|
||||
* class Seeker {
|
||||
* constructor(@Query('findMe, findMeToo') elList: QueryList<ElementRef>) {...}
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* Configure whether query looks for direct children or all descendants
|
||||
* of the querying element, by using the `descendants` parameter.
|
||||
* It is set to `false` by default.
|
||||
*
|
||||
* ### Example ([live demo](http://plnkr.co/edit/wtGeB977bv7qvA5FTYl9?p=preview))
|
||||
* ```html
|
||||
* <container #first>
|
||||
* <item>a</item>
|
||||
* <item>b</item>
|
||||
* <container #second>
|
||||
* <item>c</item>
|
||||
* </container>
|
||||
* </container>
|
||||
* ```
|
||||
*
|
||||
* When querying for items, the first container will see only `a` and `b` by default,
|
||||
* but with `Query(TextDirective, {descendants: true})` it will see `c` too.
|
||||
*
|
||||
* The queried directives are kept in a depth-first pre-order with respect to their
|
||||
* positions in the DOM.
|
||||
*
|
||||
* Query does not look deep into any subcomponent views.
|
||||
*
|
||||
* Query is updated as part of the change-detection cycle. Since change detection
|
||||
* happens after construction of a directive, QueryList will always be empty when observed in the
|
||||
* constructor.
|
||||
*
|
||||
* The injected object is an unmodifiable live list.
|
||||
* See {@link QueryList} for more details.
|
||||
*/
|
||||
export var Query: QueryFactory = makeParamDecorator(QueryMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from ContentChildrenMetadata.
|
||||
/**
|
||||
* {@link ContentChildrenMetadata} factory function.
|
||||
* Configures a content query.
|
||||
*
|
||||
* Content queries are set before the `afterContentInit` callback is called.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'someDir'
|
||||
* })
|
||||
* class SomeDir {
|
||||
* @ContentChildren(ChildDirective) contentChildren: QueryList<ChildDirective>;
|
||||
*
|
||||
* afterContentInit() {
|
||||
* // contentChildren is set
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export var ContentChildren: ContentChildrenFactory = makePropDecorator(ContentChildrenMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from ContentChildMetadata.
|
||||
/**
|
||||
* {@link ContentChildMetadata} factory function.
|
||||
* Configures a content query.
|
||||
*
|
||||
* Content queries are set before the `afterContentInit` callback is called.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'someDir'
|
||||
* })
|
||||
* class SomeDir {
|
||||
* @ContentChild(ChildDirective) contentChild;
|
||||
*
|
||||
* afterContentInit() {
|
||||
* // contentChild is set
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export var ContentChild: ContentChildFactory = makePropDecorator(ContentChildMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildrenMetadata.
|
||||
/**
|
||||
* {@link ViewChildrenMetadata} factory function.
|
||||
* Configures a view query.
|
||||
*
|
||||
* View queries are set before the `afterViewInit` callback is called.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```
|
||||
* @Component({
|
||||
* selector: 'someDir',
|
||||
* templateUrl: 'someTemplate',
|
||||
* directives: [ItemDirective]
|
||||
* })
|
||||
* class SomeDir {
|
||||
* @ViewChildren(ItemDirective) viewChildren: QueryList<ItemDirective>;
|
||||
*
|
||||
* afterViewInit() {
|
||||
* // viewChildren is set
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export var ViewChildren: ViewChildrenFactory = makePropDecorator(ViewChildrenMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildMetadata.
|
||||
/**
|
||||
* {@link ViewChildMetadata} factory function.
|
||||
* Configures a view query.
|
||||
*
|
||||
* View queries are set before the `afterViewInit` callback is called.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```
|
||||
* @Component({
|
||||
* selector: 'someDir',
|
||||
* templateUrl: 'someTemplate',
|
||||
* directives: [ItemDirective]
|
||||
* })
|
||||
* class SomeDir {
|
||||
* @ViewChild(ItemDirective) viewChild:ItemDirective;
|
||||
*
|
||||
* afterViewInit() {
|
||||
* // viewChild is set
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export var ViewChild: ViewChildFactory = makePropDecorator(ViewChildMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewQueryMetadata.
|
||||
/**
|
||||
* {@link di/ViewQueryMetadata} factory function.
|
||||
* Similar to {@link QueryMetadata}, but querying the component view, instead of
|
||||
* the content children.
|
||||
*
|
||||
* ### Example ([live demo](http://plnkr.co/edit/eNsFHDf7YjyM6IzKxM1j?p=preview))
|
||||
*
|
||||
* ```javascript
|
||||
* @Component({...})
|
||||
* @View({
|
||||
* template: `
|
||||
* <item> a </item>
|
||||
* <item> b </item>
|
||||
* <item> c </item>
|
||||
* `
|
||||
* })
|
||||
* class MyComponent {
|
||||
* shown: boolean;
|
||||
*
|
||||
* constructor(private @Query(Item) items:QueryList<Item>) {
|
||||
* items.onChange(() => console.log(items.length));
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* Supports the same querying parameters as {@link QueryMetadata}, except
|
||||
* `descendants`. This always queries the whole view.
|
||||
*
|
||||
* As `shown` is flipped between true and false, items will contain zero of one
|
||||
* items.
|
||||
*
|
||||
* Specifies that a {@link QueryList} should be injected.
|
||||
*
|
||||
* The injected object is an iterable and observable live list.
|
||||
* See {@link QueryList} for more details.
|
||||
*/
|
||||
export var ViewQuery: QueryFactory = makeParamDecorator(ViewQueryMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from PipeMetadata.
|
||||
/**
|
||||
* {@link PipeMetadata} factory function.
|
||||
* Declare reusable pipe function.
|
||||
*
|
||||
* ## Example
|
||||
*
|
||||
* ```
|
||||
* @Pipe({
|
||||
* name: 'lowercase'
|
||||
* })
|
||||
* class Lowercase {
|
||||
* transform(v, args) { return v.toLowerCase(); }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export var Pipe: PipeFactory = <PipeFactory>makeDecorator(PipeMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from InputMetadata.
|
||||
/**
|
||||
* {@link InputMetadata} factory function.
|
||||
* Declares a data-bound input property.
|
||||
*
|
||||
* See {@link InputMetadata}.
|
||||
* Angular automatically updates data-bound properties during change detection.
|
||||
*
|
||||
* `InputMetadata` takes an optional parameter that specifies the name
|
||||
* used when instantiating a component in the template. When not provided,
|
||||
* the name of the decorated property is used.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* The following example creates a component with two input properties.
|
||||
*
|
||||
* ```typescript
|
||||
* @Component({
|
||||
* selector: 'bank-account',
|
||||
* template: `
|
||||
* Bank Name: {{bankName}}
|
||||
* Account Id: {{id}}
|
||||
* `
|
||||
* })
|
||||
* class BankAccount {
|
||||
* @Input() bankName: string;
|
||||
* @Input('account-id') id: string;
|
||||
*
|
||||
* // this property is not bound, and won't be automatically updated by Angular
|
||||
* normalizedBankName: string;
|
||||
* }
|
||||
*
|
||||
* @Component({
|
||||
* selector: 'app',
|
||||
* template: `
|
||||
* <bank-account bank-name="RBC" account-id="4747"></bank-account>
|
||||
* `,
|
||||
* directives: [BankAccount]
|
||||
* })
|
||||
* class App {}
|
||||
*
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*/
|
||||
export var Input: InputFactory = makePropDecorator(InputMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from OutputMetadata.
|
||||
/**
|
||||
* {@link OutputMetadata} factory function.
|
||||
* Declares an event-bound output property.
|
||||
*
|
||||
* See {@link OutputMetadata}.
|
||||
* When an output property emits an event, an event handler attached to that event
|
||||
* the template is invoked.
|
||||
*
|
||||
* `OutputMetadata` takes an optional parameter that specifies the name
|
||||
* used when instantiating a component in the template. When not provided,
|
||||
* the name of the decorated property is used.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```typescript
|
||||
* @Directive({
|
||||
* selector: 'interval-dir',
|
||||
* })
|
||||
* class IntervalDir {
|
||||
* @Output() everySecond = new EventEmitter();
|
||||
* @Output('everyFiveSeconds') five5Secs = new EventEmitter();
|
||||
*
|
||||
* constructor() {
|
||||
* setInterval(() => this.everySecond.next("event"), 1000);
|
||||
* setInterval(() => this.five5Secs.next("event"), 5000);
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* @Component({
|
||||
* selector: 'app',
|
||||
* template: `
|
||||
* <interval-dir (every-second)="everySecond()" (every-five-seconds)="everyFiveSeconds()">
|
||||
* </interval-dir>
|
||||
* `,
|
||||
* directives: [IntervalDir]
|
||||
* })
|
||||
* class App {
|
||||
* everySecond() { console.log('second'); }
|
||||
* everyFiveSeconds() { console.log('five seconds'); }
|
||||
* }
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*/
|
||||
export var Output: OutputFactory = makePropDecorator(OutputMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from HostBindingMetadata.
|
||||
/**
|
||||
* {@link HostBindingMetadata} factory function.
|
||||
* Declares a host property binding.
|
||||
*
|
||||
* Angular automatically checks host property bindings during change detection.
|
||||
* If a binding changes, it will update the host element of the directive.
|
||||
*
|
||||
* `HostBindingMetadata` takes an optional parameter that specifies the property
|
||||
* name of the host element that will be updated. When not provided,
|
||||
* the class property name is used.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* The following example creates a directive that sets the `valid` and `invalid` classes
|
||||
* on the DOM element that has ng-model directive on it.
|
||||
*
|
||||
* ```typescript
|
||||
* @Directive({selector: '[ng-model]'})
|
||||
* class NgModelStatus {
|
||||
* constructor(public control:NgModel) {}
|
||||
* @HostBinding('[class.valid]') get valid { return this.control.valid; }
|
||||
* @HostBinding('[class.invalid]') get invalid { return this.control.invalid; }
|
||||
* }
|
||||
*
|
||||
* @Component({
|
||||
* selector: 'app',
|
||||
* template: `<input [(ng-model)]="prop">`,
|
||||
* directives: [FORM_DIRECTIVES, NgModelStatus]
|
||||
* })
|
||||
* class App {
|
||||
* prop;
|
||||
* }
|
||||
*
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*/
|
||||
export var HostBinding: HostBindingFactory = makePropDecorator(HostBindingMetadata);
|
||||
|
||||
// TODO(alexeagle): remove the duplication of this doc. It is copied from HostListenerMetadata.
|
||||
/**
|
||||
* {@link HostListenerMetadata} factory function.
|
||||
* Declares a host listener.
|
||||
*
|
||||
* Angular will invoke the decorated method when the host element emits the specified event.
|
||||
*
|
||||
* If the decorated method returns `false`, then `preventDefault` is applied on the DOM
|
||||
* event.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* The following example declares a directive that attaches a click listener to the button and
|
||||
* counts clicks.
|
||||
*
|
||||
* ```typescript
|
||||
* @Directive({selector: 'button[counting]'})
|
||||
* class CountClicks {
|
||||
* numberOfClicks = 0;
|
||||
*
|
||||
* @HostListener('click', ['$event.target'])
|
||||
* onClick(btn) {
|
||||
* console.log("button", btn, "number of clicks:", this.numberOfClicks++);
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* @Component({
|
||||
* selector: 'app',
|
||||
* template: `<button counting>Increment</button>`,
|
||||
* directives: [CountClicks]
|
||||
* })
|
||||
* class App {}
|
||||
*
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*/
|
||||
export var HostListener: HostListenerFactory = makePropDecorator(HostListenerMetadata);
|
||||
|
|
|
|||
Loading…
Reference in New Issue