docs: add api doc for ngfor (#27377)

PR Close #27377
This commit is contained in:
Judy Bogart 2018-11-30 08:26:21 -08:00 committed by Alex Rickabaugh
parent 37f8263430
commit 6c3b57a968
1 changed files with 65 additions and 41 deletions

View File

@ -26,15 +26,61 @@ export class NgForOfContext<T> {
} }
/** /**
* The `NgForOf` directive instantiates a template once per item from an iterable. The context * A [structural directive](guide/structural-directives) that renders
* for each instantiated template inherits from the outer context with the given loop variable * a template for each item in a collection.
* set to the current item from the iterable. * The directive is placed on an element, which becomes the parent
* of the cloned templates.
*
* The `ngForOf` is generally used in the
* [shorthand form](guide/structural-directives#the-asterisk--prefix) `*ngFor`.
* In this form, the template to be rendered for each iteration is the content
* of an anchor element containing the directive.
*
* The following example shows the shorthand syntax with some options,
* contained in an `<li>` element.
*
* ```
* <li *ngFor="let item of items; index as i; trackBy: trackByFn">...</li>
* ```
*
* The shorthand form expands into a long form that uses the `ngForOf` selector
* on an `<ng-template>` element.
* The content of the `<ng-template>` element is the `<li>` element that held the
* short-form directive.
*
* Here is the expanded version of the short-form example.
*
* ```
* <ng-template ngFor let-item [ngForOf]="items" let-i="index" [ngForTrackBy]="trackByFn">
* <li>...</li>
* </ng-template>
* ```
*
* Angular automatically expands the shorthand syntax as it compiles the template.
* The context for each embedded view is logically merged to the current component
* context according to its lexical position.
*
* When using the shorthand syntax, Angular allows only [one structural directive
* on an element](guide/structural-directives#one-structural-directive-per-host-element).
* If you want to iterate conditionally, for example,
* put the `*ngIf` on a container element that wraps the `*ngFor` element.
* For futher discussion, see
* [Structural Directives](guide/structural-directives#one-per-element).
* *
* @usageNotes * @usageNotes
* *
* ### Local Variables * ### Local variables
* *
* `NgForOf` provides several exported values that can be aliased to local variables: * `NgForOf` provides exported values that can be aliased to local variables.
* For example:
*
* ```
* <li *ngFor="let user of userObservable | async as users; index as i; first as isFirst">
* {{i}}/{{users.length}}. {{user}} <span *ngIf="isFirst">default</span>
* </li>
* ```
*
* The following exported values can be aliased to local variables:
* *
* - `$implicit: T`: The value of the individual items in the iterable (`ngForOf`). * - `$implicit: T`: The value of the individual items in the iterable (`ngForOf`).
* - `ngForOf: NgIterable<T>`: The value of the iterable expression. Useful when the expression is * - `ngForOf: NgIterable<T>`: The value of the iterable expression. Useful when the expression is
@ -46,55 +92,33 @@ export class NgForOfContext<T> {
* - `even: boolean`: True when the item has an even index in the iterable. * - `even: boolean`: True when the item has an even index in the iterable.
* - `odd: boolean`: True when the item has an odd index in the iterable. * - `odd: boolean`: True when the item has an odd index in the iterable.
* *
* ``` * ### Change propagation
* <li *ngFor="let user of userObservable | async as users; index as i; first as isFirst">
* {{i}}/{{users.length}}. {{user}} <span *ngIf="isFirst">default</span>
* </li>
* ```
*
* ### Change Propagation
* *
* When the contents of the iterator changes, `NgForOf` makes the corresponding changes to the DOM: * When the contents of the iterator changes, `NgForOf` makes the corresponding changes to the DOM:
* *
* * When an item is added, a new instance of the template is added to the DOM. * * When an item is added, a new instance of the template is added to the DOM.
* * When an item is removed, its template instance is removed from the DOM. * * When an item is removed, its template instance is removed from the DOM.
* * When items are reordered, their respective templates are reordered in the DOM. * * When items are reordered, their respective templates are reordered in the DOM.
* * Otherwise, the DOM element for that item will remain the same.
* *
* Angular uses object identity to track insertions and deletions within the iterator and reproduce * Angular uses object identity to track insertions and deletions within the iterator and reproduce
* those changes in the DOM. This has important implications for animations and any stateful * those changes in the DOM. This has important implications for animations and any stateful
* controls (such as `<input>` elements which accept user input) that are present. Inserted rows can * controls that are present, such as `<input>` elements that accept user input. Inserted rows can
* be animated in, deleted rows can be animated out, and unchanged rows retain any unsaved state * be animated in, deleted rows can be animated out, and unchanged rows retain any unsaved state
* such as user input. * such as user input.
* For more on animations, see [Transitions and Triggers](guide/transition-and-triggers).
* *
* It is possible for the identities of elements in the iterator to change while the data does not. * The identities of elements in the iterator can change while the data does not.
* This can happen, for example, if the iterator produced from an RPC to the server, and that * This can happen, for example, if the iterator is produced from an RPC to the server, and that
* RPC is re-run. Even if the data hasn't changed, the second response will produce objects with * RPC is re-run. Even if the data hasn't changed, the second response produces objects with
* different identities, and Angular will tear down the entire DOM and rebuild it (as if all old * different identities, and Angular must tear down the entire DOM and rebuild it (as if all old
* elements were deleted and all new elements inserted). This is an expensive operation and should * elements were deleted and all new elements inserted).
* be avoided if possible.
* *
* To customize the default tracking algorithm, `NgForOf` supports `trackBy` option. * To avoid this expensive operation, you can customize the default tracking algorithm.
* `trackBy` takes a function which has two arguments: `index` and `item`. * by supplying the `trackBy` option to `NgForOf`.
* `trackBy` takes a function that has two arguments: `index` and `item`.
* If `trackBy` is given, Angular tracks changes by the return value of the function. * If `trackBy` is given, Angular tracks changes by the return value of the function.
* *
* ### Syntax * @see [Structural Directives](guide/structural-directives)
*
* - `<li *ngFor="let item of items; index as i; trackBy: trackByFn">...</li>`
*
* With `<ng-template>` element:
*
* ```
* <ng-template ngFor let-item [ngForOf]="items" let-i="index" [ngForTrackBy]="trackByFn">
* <li>...</li>
* </ng-template>
* ```
*
* ### Example
*
* See a [live demo](http://plnkr.co/edit/KVuXxDp0qinGDyo307QW?p=preview) for a more detailed
* example.
*
* @ngModule CommonModule * @ngModule CommonModule
* @publicApi * @publicApi
*/ */
@ -204,9 +228,9 @@ export class NgForOf<T> implements DoCheck {
} }
/** /**
* Assert the correct type of the context for the template that `NgForOf` will render. * Asserts the correct type of the context for the template that `NgForOf` will render.
* *
* The presence of this method is a signal to the Ivy template type check compiler that the * The presence of this method is a signal to the Ivy template type-check compiler that the
* `NgForOf` structural directive renders its template with a specific context type. * `NgForOf` structural directive renders its template with a specific context type.
*/ */
static ngTemplateContextGuard<T>(dir: NgForOf<T>, ctx: any): ctx is NgForOfContext<T> { static ngTemplateContextGuard<T>(dir: NgForOf<T>, ctx: any): ctx is NgForOfContext<T> {