@@ -301,23 +301,77 @@ class ViewQueryMetadata extends QueryMetadata {
301301}
302302
303303/**
304- * Configures a view query .
304+ * Declares a list of child element references .
305305 *
306- * View queries are set before the `ngAfterViewInit` callback is called.
306+ * Angular automatically updates the list when the DOM was updated.
307+ *
308+ * `ViewChildren` takes an argument to select elements.
309+ *
310+ * - If the argument is a type, directives or components with the type will be bound.
311+ *
312+ * - If the argument is a string, the string behaviors as comma-separated selectors. For each
313+ * selector, an element matched template variables (e.g. `#child` ) will be bound.
314+ *
315+ * View children are set before the `ngAfterViewInit` callback is called.
307316 *
308317 * ### Example
309318 *
319+ * With type selector:
320+ *
310321 * ```
311322 * @Component({
312- * selector: 'someDir',
313- * templateUrl: 'someTemplate',
314- * directives: [ItemDirective]
323+ * selector: 'child-cmp',
324+ * template: '<p>child</p>'
315325 * })
316- * class SomeDir {
317- * @ViewChildren(ItemDirective) viewChildren: QueryList<ItemDirective>;
326+ * class ChildCmp {
327+ * doSomething() {}
328+ * }
329+ *
330+ * @Component({
331+ * selector: 'some-cmp',
332+ * template: `
333+ * <child-cmp></child-cmp>
334+ * <child-cmp></child-cmp>
335+ * <child-cmp></child-cmp>
336+ * `,
337+ * directives: [ChildCmp]
338+ * })
339+ * class SomeCmp {
340+ * @ViewChildren(ChildCmp) children:QueryList<ChildCmp>;
341+ *
342+ * ngAfterViewInit() {
343+ * // children are set
344+ * this.children.toArray().forEach((child)=>child.doSomething());
345+ * }
346+ * }
347+ * ```
348+ *
349+ * With string selector:
350+ *
351+ * ```
352+ * @Component({
353+ * selector: 'child-cmp',
354+ * template: '<p>child</p>'
355+ * })
356+ * class ChildCmp {
357+ * doSomething() {}
358+ * }
359+ *
360+ * @Component({
361+ * selector: 'some-cmp',
362+ * template: `
363+ * <child-cmp #child1></child-cmp>
364+ * <child-cmp #child2></child-cmp>
365+ * <child-cmp #child3></child-cmp>
366+ * `,
367+ * directives: [ChildCmp]
368+ * })
369+ * class SomeCmp {
370+ * @ViewChildren('child1,child2,child3') children:QueryList<ChildCmp>;
318371 *
319372 * ngAfterViewInit() {
320- * // viewChildren is set
373+ * // children are set
374+ * this.children.toArray().forEach((child)=>child.doSomething());
321375 * }
322376 * }
323377 * ```
@@ -328,23 +382,71 @@ class ViewChildrenMetadata extends ViewQueryMetadata {
328382}
329383
330384/**
331- * Configures a view query.
332385 *
333- * View queries are set before the `ngAfterViewInit` callback is called.
386+ * Declares a reference of child element.
387+ *
388+ * `ViewChildren` takes an argument to select elements.
389+ *
390+ * - If the argument is a type, a directive or a component with the type will be bound.
391+ *
392+ * - If the argument is a string, the string behaviors as a selectors. An element matched template
393+ * variables (e.g. `#child` ) will be bound.
394+ *
395+ * In either case, `@ViewChild()` assigns the first (looking from above) element if the result is
396+ * multiple.
397+ *
398+ * View child is set before the `ngAfterViewInit` callback is called.
334399 *
335400 * ### Example
336401 *
402+ * With type selector:
403+ *
337404 * ```
338405 * @Component({
339- * selector: 'someDir',
340- * templateUrl: 'someTemplate',
341- * directives: [ItemDirective]
406+ * selector: 'child-cmp',
407+ * template: '<p>child</p>'
342408 * })
343- * class SomeDir {
344- * @ViewChild(ItemDirective) viewChild:ItemDirective;
409+ * class ChildCmp {
410+ * doSomething() {}
411+ * }
412+ *
413+ * @Component({
414+ * selector: 'some-cmp',
415+ * template: '<child-cmp></child-cmp>',
416+ * directives: [ChildCmp]
417+ * })
418+ * class SomeCmp {
419+ * @ViewChild(ChildCmp) child:ChildCmp;
420+ *
421+ * ngAfterViewInit() {
422+ * // child is set
423+ * this.child.doSomething();
424+ * }
425+ * }
426+ * ```
427+ *
428+ * With string selector:
429+ *
430+ * ```
431+ * @Component({
432+ * selector: 'child-cmp',
433+ * template: '<p>child</p>'
434+ * })
435+ * class ChildCmp {
436+ * doSomething() {}
437+ * }
438+ *
439+ * @Component({
440+ * selector: 'some-cmp',
441+ * template: '<child-cmp #child></child-cmp>',
442+ * directives: [ChildCmp]
443+ * })
444+ * class SomeCmp {
445+ * @ViewChild('child') child:ChildCmp;
345446 *
346447 * ngAfterViewInit() {
347- * // viewChild is set
448+ * // child is set
449+ * this.child.doSomething();
348450 * }
349451 * }
350452 * ```
0 commit comments