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

Commit 0f7bcfd

Browse files
teropabtford
authored andcommitted
docs(guide/scope): describe watch depths
Describe and visualize the three watch strategies: By reference, by collection items, and by value. Closes #9388
1 parent 9a26ab5 commit 0f7bcfd

File tree

2 files changed

+12
-0
lines changed

2 files changed

+12
-0
lines changed

docs/content/guide/scope.ngdoc

+12
Original file line numberDiff line numberDiff line change
@@ -339,6 +339,18 @@ the dirty checking function must be efficient. Care should be taken that the dir
339339
function does not do any DOM access, as DOM access is orders of magnitude slower than property
340340
access on JavaScript object.
341341

342+
### Scope `$watch` Depths
343+
<img class="pull-right" style="padding-left: 3em; padding-bottom: 1em;" src="img/guide/concepts-scope-watch-strategies.png">
344+
345+
Dirty checking can be done with three strategies: By reference, by collection contents, and by value. The strategies differ in the kinds of changes they detect, and in their performance characteristics.
346+
347+
- Watching *by reference* ({@link
348+
ng.$rootScope.Scope#$watch scope.$watch} `(watchExpression, listener)`) detects a change when the whole value returned by the watch expression switches to a new value. If the value is an array or an object, changes inside it are not detected. This is the most efficient stategy.
349+
- Watching *collection contents* ({@link
350+
ng.$rootScope.Scope#$watchCollection scope.$watchCollection} `(watchExpression, listener)`) detects changes that occur inside an array or an object: When items are added, removed, or reordered. The detection is shallow - it does not reach into nested collections. Watching collection contents is more expensive than watching by reference, because copies of the collection contents need to be maintained. However, the strategy attempts to minimize the amount of copying required.
351+
- Watching *by value* ({@link
352+
ng.$rootScope.Scope#$watch scope.$watch} `(watchExpression, listener, true)`) detects any change in an arbitrarily nested data structure. It is the most powerful change detection strategy, but also the most expensive. A full traversal of the nested data structure is needed on each digest, and a full copy of it needs to be held in memory.
353+
342354
## Integration with the browser event loop
343355
<img class="pull-right" style="padding-left: 3em; padding-bottom: 1em;" src="img/guide/concepts-runtime.png">
344356

Loading

0 commit comments

Comments
 (0)