Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit ca53dfc

Browse files
committed
docs(ngRepeat): add more info about watching and tracking
- mention $watchCollection - highlight that track by "id" can improve render performance Related #9508
1 parent ce6a96b commit ca53dfc

File tree

1 file changed

+17
-7
lines changed

1 file changed

+17
-7
lines changed

src/ng/directive/ngRepeat.js

+17-7
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,21 @@
5353
*
5454
* # Tracking and Duplicates
5555
*
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:
5758
*
5859
* * When an item is added, a new instance of the template is added to the DOM.
5960
* * When an item is removed, its template instance is removed from the DOM.
6061
* * When items are reordered, their respective templates are reordered in the DOM.
6162
*
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.
6571
*
6672
* If you do need to repeat duplicate items, you can substitute the default tracking behavior
6773
* with your own using the `track by` expression.
@@ -74,18 +80,22 @@
7480
* </div>
7581
* ```
7682
*
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
7884
* on the scope:
7985
* ```html
8086
* <div ng-repeat="n in [42, 42, 43, 43] track by myTrackingFunction(n)">
8187
* {{n}}
8288
* </div>
8389
* ```
8490
*
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
8693
* by the identifier instead of the whole object. Should you reload your data later, `ngRepeat`
8794
* 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>
8999
* ```html
90100
* <div ng-repeat="model in collection track by model.id">
91101
* {{model.name}}

0 commit comments

Comments
 (0)