You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: adev/src/content/guide/templates/control-flow.md
+60-38Lines changed: 60 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,88 +2,104 @@
2
2
3
3
Angular templates support *control flow blocks* that let you conditionally show, hide, and repeat elements.
4
4
5
-
IMPORTANT: Angular built-in control flow is in [developer preview](reference/releases#developer-preview). It is ready to try, but may change before becoming stable.
5
+
IMPORTANT: Angular built-in control flow is in [developer preview](reference/releases#developer-preview). It is ready to
6
+
try, but may change before becoming stable.
6
7
7
8
## `@if` block conditionals
8
9
9
10
The `@if` block conditionally displays its content when its condition expression is truthy:
10
11
11
12
```html
12
13
@if (a > b) {
13
-
{{a}} is greater than {{b}}
14
+
{{a}} is greater than {{b}}
14
15
}
15
16
```
16
17
17
-
The `@if` block might have one or more associated `@else` blocks. Immediately after an `@if` block, you can optionally specify any number of `@else if` blocks and one `@else` block:
18
+
The `@if` block might have one or more associated `@else` blocks. Immediately after an `@if` block, you can optionally
19
+
specify any number of `@else if` blocks and one `@else` block:
18
20
19
21
```html
20
22
@if (a > b) {
21
-
{{a}} is greater than {{b}}
23
+
{{a}} is greater than {{b}}
22
24
} @else if (b > a) {
23
-
{{a}} is less than {{b}}
25
+
{{a}} is less than {{b}}
24
26
} @else {
25
-
{{a}} is equal to {{b}}
27
+
{{a}} is equal to {{b}}
26
28
}
27
29
```
28
30
29
31
### Referencing the conditional expression's result
30
32
31
-
The new built-in `@if` conditional supports referencing of expression results to keep a solution for common coding patterns:
33
+
The new built-in `@if` conditional supports referencing of expression results to keep a solution for common coding
34
+
patterns:
32
35
33
36
```html
34
37
@if (users$ | async; as users) {
35
-
{{ users.length }}
38
+
{{ users.length }}
36
39
}
37
40
```
38
41
39
42
## `@for` block - repeaters
40
43
41
-
The `@for` repeatedly renders content of a block for each item in a collection. The collection can be represented as any JavaScript [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) but there are performance advantages of using a regular `Array`. A basic `@for` loop looks like:
44
+
The `@for` repeatedly renders content of a block for each item in a collection. The collection can be represented as any
45
+
JavaScript [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) but there
46
+
are performance advantages of using a regular `Array`. A basic `@for` loop looks like:
42
47
43
48
```html
44
49
@for (item of items; track item.id) {
45
-
{{ item.name }}
50
+
{{ item.name }}
46
51
}
47
52
```
48
53
49
54
### `track` for calculating difference of two collections
50
55
51
-
The value of the `track` expression determines a key used to associate array items with the views in the DOM. Having clear indication of the item identity allows Angular to execute a minimal set of DOM operations as items are added, removed or moved in a collection.
56
+
The value of the `track` expression determines a key used to associate array items with the views in the DOM. Having
57
+
clear indication of the item identity allows Angular to execute a minimal set of DOM operations as items are added,
58
+
removed or moved in a collection.
52
59
53
-
Loops over immutable data without `trackBy` are one of the most common causes for performance issues across Angular applications. Because of the potential for poor performance, the `track` expression is required for the `@for` loops. When in doubt, using `track $index` is a good default.
60
+
Using track effectively can significantly enhance your application's performance, especially in loops over data
61
+
collections.
62
+
63
+
For collections that do not undergo modifications (no items are moved, added, or deleted), using `track $index` is an
64
+
efficient strategy. For collections with mutable data or frequent changes, select a property that uniquely identifies
65
+
each item to use as your track expression.
66
+
67
+
Be aware of the potential for increased DOM re-creation when using object identity as a track key with immutable data
68
+
structures, as this can lead to unnecessary performance costs.
54
69
55
70
### `$index` and other contextual variables
56
71
57
72
Inside `@for` contents, several implicit variables are always available:
|`$count`| Number of items in a collection iterated over |
62
-
|`$index`| Index of the current row |
63
-
|`$first`| Whether the current row is the first row |
64
-
|`$last`| Whether the current row is the last row |
65
-
|`$even`| Whether the current row index is even |
66
-
|`$odd`| Whether the current row index is odd |
77
+
|`$index`| Index of the current row |
78
+
|`$first`| Whether the current row is the first row |
79
+
|`$last`| Whether the current row is the last row|
80
+
|`$even`| Whether the current row index is even|
81
+
|`$odd`| Whether the current row index is odd|
67
82
68
83
These variables are always available with these names, but can be aliased via a `let` segment:
69
84
70
85
```html
71
86
@for (item of items; track item.id; let idx = $index, e = $even) {
72
-
Item #{{ idx }}: {{ item.name }}
87
+
Item #{{ idx }}: {{ item.name }}
73
88
}
74
89
```
75
90
76
91
The aliasing is especially useful in case of using nested `@for` blocks where contextual variable names could collide.
77
92
78
93
### `empty` block
79
94
80
-
You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty` block displays when there are no items:
95
+
You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty`
96
+
block displays when there are no items:
81
97
82
98
```html
83
99
@for (item of items; track item.name) {
84
-
<li> {{ item.name }}</li>
100
+
<li> {{ item.name }}</li>
85
101
} @empty {
86
-
<li> There are no items.</li>
102
+
<li> There are no items.</li>
87
103
}
88
104
```
89
105
@@ -93,23 +109,24 @@ The syntax for `switch` is very similar to `if`, and is inspired by the JavaScri
93
109
94
110
```html
95
111
@switch (condition) {
96
-
@case (caseA) {
97
-
Case A.
98
-
}
99
-
@case (caseB) {
100
-
Case B.
101
-
}
102
-
@default {
103
-
Default case.
104
-
}
112
+
@case (caseA) {
113
+
Case A.
114
+
}
115
+
@case (caseB) {
116
+
Case B.
117
+
}
118
+
@default {
119
+
Default case.
120
+
}
105
121
}
106
122
```
107
123
108
124
The value of the conditional expression is compared to the case expression using the `===` operator.
109
125
110
126
**`@switch` does not have fallthrough**, so you do not need an equivalent to a `break` or `return` statement.
111
127
112
-
The `@default` block is optional and can be omitted. If no `@case` matches the expression and there is no `@default` block, nothing is shown.
128
+
The `@default` block is optional and can be omitted. If no `@case` matches the expression and there is no `@default`
129
+
block, nothing is shown.
113
130
114
131
## Built-in control flow and the `NgIf`, `NgSwitch` and `NgFor` structural directives
115
132
@@ -120,16 +137,21 @@ The `@switch` block replaces `ngSwitch` with major benefits:
120
137
* it does not require a container element to hold the condition expression or each conditional template;
121
138
* it supports template type-checking, including type narrowing within each branch.
122
139
123
-
The `@for` block replaces `*ngFor` for iteration, and has several differences compared to its structural directive `NgFor` predecessor:
140
+
The `@for` block replaces `*ngFor` for iteration, and has several differences compared to its structural
141
+
directive `NgFor` predecessor:
124
142
125
-
* tracking expression (calculating keys corresponding to object identities) is mandatory but has better ergonomics (it is enough to write an expression instead of creating the `trackBy` method);
126
-
* uses a new optimized algorithm for calculating a minimal number of DOM operations to be performed in response to changes in a collection, instead of Angular’s customizable diffing implementation (`IterableDiffer`);
143
+
* tracking expression (calculating keys corresponding to object identities) is mandatory but has better ergonomics (it
144
+
is enough to write an expression instead of creating the `trackBy` method);
145
+
* uses a new optimized algorithm for calculating a minimal number of DOM operations to be performed in response to
146
+
changes in a collection, instead of Angular’s customizable diffing implementation (`IterableDiffer`);
127
147
* has support for `@empty` blocks.
128
148
129
-
The `track` setting replaces `NgFor`'s concept of a `trackBy` function. Because `@for` is built-in, we can provide a better experience than passing a `trackBy` function, and directly use an expression representing the key instead. Migrating from `trackBy` to `track` is possible by invoking the `trackBy` function:
149
+
The `track` setting replaces `NgFor`'s concept of a `trackBy` function. Because `@for` is built-in, we can provide a
150
+
better experience than passing a `trackBy` function, and directly use an expression representing the key instead.
151
+
Migrating from `trackBy` to `track` is possible by invoking the `trackBy` function:
130
152
131
153
```html
132
154
@for (item of items; track itemId($index, item)) {
Copy file name to clipboardExpand all lines: aio/content/blocks/core/for.md
+28-16Lines changed: 28 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,43 +4,55 @@ The `@for` block repeatedly renders content of a block for each item in a collec
4
4
5
5
```html
6
6
@for (item of items; track item.name) {
7
-
<li>{{ item.name }}</li>
7
+
<li>{{ item.name }}</li>
8
8
} @empty {
9
-
<li>There are no items.</li>
9
+
<li>There are no items.</li>
10
10
}
11
11
```
12
12
13
13
@description
14
14
15
-
The `@for` block renders its content in response to changes in a collection. Collections can be any JavaScript [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols), but there are performance advantages of using a regular `Array`.
15
+
The `@for` block renders its content in response to changes in a collection. Collections can be any
but there are performance advantages of using a regular `Array`.
16
18
17
-
You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty` block displays when there are no items.
19
+
You can optionally include an `@empty` section immediately after the `@for` block content. The
20
+
content of the `@empty` block displays when there are no items.
18
21
19
22
<h3> track and objects identity </h3>
20
23
21
-
The value of the `track` expression determines a key used to associate array items with the views in the DOM. Having clear indication of the item identity allows Angular to execute a minimal set of DOM operations as items are added, removed or moved in a collection.
24
+
The value of the `track` expression determines a key used to associate array items with the views in
25
+
the DOM. Having clear indication of the item identity allows Angular to execute a minimal set of DOM
26
+
operations as items are added, removed or moved in a collection.
22
27
23
-
Loops over immutable data without `trackBy` as one of the most common causes for performance issues across Angular applications. Because of the potential for poor performance, the `track` expression is required for the `@for` loops. When in doubt, using `track $index` is a good default.
28
+
To optimize performance, especially in loops over immutable data, ensure the track expression is effectively used to
29
+
identify each item uniquely. Because of the potential for poor performance, the `track` expression
30
+
is required for the `@for` loops.
31
+
32
+
For collections that remain static , `track $index` provides a straightforward tracking mechanism. For dynamic
33
+
collections experiencing additions, deletions, or reordering, opt for a
34
+
unique property of each item as the tracking key.
24
35
25
36
<h3> `$index` and other contextual variables </h3>
26
37
27
-
Inside `@for`contents, several implicit variables are always available:
38
+
Inside `@for` contents, several implicit variables are always available:
0 commit comments