docs(metadata): Add more docs of ViewChild and ViewChildren

Closes #7174
This commit is contained in:
laco0416 2016-02-19 15:31:27 +09:00 committed by Robert Messerle
parent a5d6b6db8b
commit e9f7a00910
2 changed files with 238 additions and 32 deletions

View File

@ -1093,51 +1093,155 @@ export var ContentChild: ContentChildFactory = makePropDecorator(ContentChildMet
// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildrenMetadata.
/**
* Configures a view query.
* Declares a list of child element references.
*
* View queries are set before the `ngAfterViewInit` callback is called.
* Angular automatically updates the list when the DOM was updated.
*
* `ViewChildren` takes a argument to select elements.
*
* - If the argument is a type, directives or components with the type will be bound.
*
* - If the argument is a string, the string behaviors as comma-separated selectors. For each
* selector, an element matched template variables (e.g. `#child`) will be bound.
*
* View children are set before the `ngAfterViewInit` callback is called.
*
* ### Example
*
* With type selector:
*
* ```
* @Component({
* selector: 'someDir',
* templateUrl: 'someTemplate',
* directives: [ItemDirective]
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class SomeDir {
* @ViewChildren(ItemDirective) viewChildren: QueryList<ItemDirective>;
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: `
* <child-cmp></child-cmp>
* <child-cmp></child-cmp>
* <child-cmp></child-cmp>
* `,
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChildren(ChildCmp) children:QueryList<ChildCmp>;
*
* ngAfterViewInit() {
* // viewChildren is set
* // children are set
* this.children.toArray().forEach((child)=>child.doSomething());
* }
* }
* ```
*
* With string selector:
*
* ```
* @Component({
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: `
* <child-cmp #child1></child-cmp>
* <child-cmp #child2></child-cmp>
* <child-cmp #child3></child-cmp>
* `,
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChildren('child1,child2,child3') children:QueryList<ChildCmp>;
*
* ngAfterViewInit() {
* // children are set
* this.children.toArray().forEach((child)=>child.doSomething());
* }
* }
* ```
*
* See also: [ViewChildrenMetadata]
*/
export var ViewChildren: ViewChildrenFactory = makePropDecorator(ViewChildrenMetadata);
// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildMetadata.
/**
* Configures a view query.
* Declares a reference of child element.
*
* View queries are set before the `ngAfterViewInit` callback is called.
* `ViewChildren` takes a argument to select elements.
*
* - If the argument is a type, a directive or a component with the type will be bound.
*
* - If the argument is a string, the string behaviors as a selectors. An element matched template
* variables (e.g. `#child`) will be bound.
*
* In either case, `@ViewChild()` assigns the first (looking from above) element if the result is
* multiple.
*
* View child is set before the `ngAfterViewInit` callback is called.
*
* ### Example
*
* With type selector:
*
* ```
* @Component({
* selector: 'someDir',
* templateUrl: 'someTemplate',
* directives: [ItemDirective]
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class SomeDir {
* @ViewChild(ItemDirective) viewChild:ItemDirective;
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: '<child-cmp></child-cmp>',
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChild(ChildCmp) child:ChildCmp;
*
* ngAfterViewInit() {
* // viewChild is set
* // child is set
* this.child.doSomething();
* }
* }
* ```
*
* With string selector:
*
* ```
* @Component({
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: '<child-cmp #child></child-cmp>',
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChild('child') child:ChildCmp;
*
* ngAfterViewInit() {
* // child is set
* this.child.doSomething();
* }
* }
* ```
* See also: [ViewChildMetadata]
*/
export var ViewChild: ViewChildFactory = makePropDecorator(ViewChildMetadata);

View File

@ -285,23 +285,77 @@ export class ViewQueryMetadata extends QueryMetadata {
}
/**
* Configures a view query.
* Declares a list of child element references.
*
* View queries are set before the `ngAfterViewInit` callback is called.
* Angular automatically updates the list when the DOM was updated.
*
* `ViewChildren` takes an argument to select elements.
*
* - If the argument is a type, directives or components with the type will be bound.
*
* - If the argument is a string, the string behaviors as comma-separated selectors. For each
* selector, an element matched template variables (e.g. `#child`) will be bound.
*
* View children are set before the `ngAfterViewInit` callback is called.
*
* ### Example
*
* With type selector:
*
* ```
* @Component({
* selector: 'someDir',
* templateUrl: 'someTemplate',
* directives: [ItemDirective]
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class SomeDir {
* @ViewChildren(ItemDirective) viewChildren: QueryList<ItemDirective>;
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: `
* <child-cmp></child-cmp>
* <child-cmp></child-cmp>
* <child-cmp></child-cmp>
* `,
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChildren(ChildCmp) children:QueryList<ChildCmp>;
*
* ngAfterViewInit() {
* // viewChildren is set
* // children are set
* this.children.toArray().forEach((child)=>child.doSomething());
* }
* }
* ```
*
* With string selector:
*
* ```
* @Component({
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: `
* <child-cmp #child1></child-cmp>
* <child-cmp #child2></child-cmp>
* <child-cmp #child3></child-cmp>
* `,
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChildren('child1,child2,child3') children:QueryList<ChildCmp>;
*
* ngAfterViewInit() {
* // children are set
* this.children.toArray().forEach((child)=>child.doSomething());
* }
* }
* ```
@ -312,23 +366,71 @@ export class ViewChildrenMetadata extends ViewQueryMetadata {
}
/**
* Configures a view query.
*
* View queries are set before the `ngAfterViewInit` callback is called.
* Declares a reference of child element.
*
* `ViewChildren` takes an argument to select elements.
*
* - If the argument is a type, a directive or a component with the type will be bound.
*
* - If the argument is a string, the string behaviors as a selectors. An element matched template
* variables (e.g. `#child`) will be bound.
*
* In either case, `@ViewChild()` assigns the first (looking from above) element if the result is
* multiple.
*
* View child is set before the `ngAfterViewInit` callback is called.
*
* ### Example
*
* With type selector:
*
* ```
* @Component({
* selector: 'someDir',
* templateUrl: 'someTemplate',
* directives: [ItemDirective]
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class SomeDir {
* @ViewChild(ItemDirective) viewChild:ItemDirective;
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: '<child-cmp></child-cmp>',
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChild(ChildCmp) child:ChildCmp;
*
* ngAfterViewInit() {
* // viewChild is set
* // child is set
* this.child.doSomething();
* }
* }
* ```
*
* With string selector:
*
* ```
* @Component({
* selector: 'child-cmp',
* template: '<p>child</p>'
* })
* class ChildCmp {
* doSomething() {}
* }
*
* @Component({
* selector: 'some-cmp',
* template: '<child-cmp #child></child-cmp>',
* directives: [ChildCmp]
* })
* class SomeCmp {
* @ViewChild('child') child:ChildCmp;
*
* ngAfterViewInit() {
* // child is set
* this.child.doSomething();
* }
* }
* ```