|
53 | 53 | *
|
54 | 54 | * # Tracking and Duplicates
|
55 | 55 | *
|
56 |
| - * When the contents of the collection change, `ngRepeat` makes the corresponding changes to the DOM: |
| 56 | + * `ngRepeat` uses {@link $rootScope.Scope#$watchCollection $watchCollection} to detect changes in |
| 57 | + * the collection. When a change happens, ngRepeat then makes the corresponding changes to the DOM: |
57 | 58 | *
|
58 | 59 | * * When an item is added, a new instance of the template is added to the DOM.
|
59 | 60 | * * When an item is removed, its template instance is removed from the DOM.
|
60 | 61 | * * When items are reordered, their respective templates are reordered in the DOM.
|
61 | 62 | *
|
62 |
| - * By default, `ngRepeat` does not allow duplicate items in arrays. This is because when |
63 |
| - * there are duplicates, it is not possible to maintain a one-to-one mapping between collection |
64 |
| - * items and DOM elements. |
| 63 | + * To minimize creation of DOM elements, `ngRepeat` uses a function |
| 64 | + * to "keep track" of all items in the collection and their corresponding DOM elements. |
| 65 | + * For example, if an item is added to the collection, ngRepeat will know that all other items |
| 66 | + * already have DOM elements, and will not re-render them. |
| 67 | + * |
| 68 | + * The default tracking function (which tracks items by their identity) does not allow |
| 69 | + * duplicate items in arrays. This is because when there are duplicates, it is not possible |
| 70 | + * to maintain a one-to-one mapping between collection items and DOM elements. |
65 | 71 | *
|
66 | 72 | * If you do need to repeat duplicate items, you can substitute the default tracking behavior
|
67 | 73 | * with your own using the `track by` expression.
|
|
74 | 80 | * </div>
|
75 | 81 | * ```
|
76 | 82 | *
|
77 |
| - * You may use arbitrary expressions in `track by`, including references to custom functions |
| 83 | + * You may also use arbitrary expressions in `track by`, including references to custom functions |
78 | 84 | * on the scope:
|
79 | 85 | * ```html
|
80 | 86 | * <div ng-repeat="n in [42, 42, 43, 43] track by myTrackingFunction(n)">
|
81 | 87 | * {{n}}
|
82 | 88 | * </div>
|
83 | 89 | * ```
|
84 | 90 | *
|
85 |
| - * If you are working with objects that have an identifier property, you can track |
| 91 | + * <div class="alert alert-success"> |
| 92 | + * If you are working with objects that have an identifier property, you should track |
86 | 93 | * by the identifier instead of the whole object. Should you reload your data later, `ngRepeat`
|
87 | 94 | * will not have to rebuild the DOM elements for items it has already rendered, even if the
|
88 |
| - * JavaScript objects in the collection have been substituted for new ones: |
| 95 | + * JavaScript objects in the collection have been substituted for new ones. For large collections, |
| 96 | + * this signifincantly improves rendering performance. If you don't have a unique identifier, |
| 97 | + * `track by $index` can also provide a performance boost. |
| 98 | + * </div> |
89 | 99 | * ```html
|
90 | 100 | * <div ng-repeat="model in collection track by model.id">
|
91 | 101 | * {{model.name}}
|
|
0 commit comments