1# Repeat
2
3When **virtualScroll** is disabled, the **Repeat** component, which is used together with the container component, performs loop rendering based on array data. In addition, the component returned by the API should be a child component that can be contained in the **Repeat** parent container. Compared with ForEach, **Repeat** optimizes the rendering performance in some update scenarios and generates function with the index maintained by the framework.
4
5When **virtualScroll** is enabled, **Repeat** iterates data from the provided data source as required and creates the corresponding component during each iteration. When **Repeat** is used in the scrolling container, the framework creates components as required based on the visible area of the scrolling container. When a component slides out of the visible area, the framework caches the component and uses it in the next iteration.
6
7>**NOTE**
8>
9> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
10>
11> State management V2 is still under development, and some features may be incomplete or not always work as expected.
12
13**Widget capability**: This API can be used in ArkTS widgets since API version 12.
14
15**System capability**: SystemCapability.ArkUI.ArkUI.Full
16
17**Parameters**
18
19| Name| Type      | Mandatory| Description     |
20| ------ | ---------- | -------- | -------- |
21| arr    | Array\<T\> | Yes| Data source, which is an array of the **Array\<T>** type. You can determine the data types.|
22
23**Return value**
24
25| Type| Description|
26| --- | --- |
27| [RepeatAttribute](#repeatattribute)\<T\> | Repeat attributes.|
28
29## RepeatAttribute
30
31### each
32
33each(itemGenerator: (repeatItem: RepeatItem\<T\>) => void): RepeatAttribute\<T\>
34
35Component generator. Data items that do not match **template** and **templateId** are generated using the **each** function by default.
36
37**NOTE**
38
39- The **each** attribute is mandatory. Otherwise, an error occurs during running.
40- The parameter of **itemGenerator** is **RepeatItem**, which combines **item** and **index**. Do not split the **RepeatItem** and use it separately.
41
42**Widget capability**: This API can be used in ArkTS widgets since API version 12.
43
44**Atomic service API**: This API can be used in atomic services since API version 12.
45
46**System capability**: SystemCapability.ArkUI.ArkUI.Full
47
48**Parameters**
49
50| Name| Type  | Mandatory| Description|
51| ------ | ---------- | -------- | -------- |
52| repeatItem  | [RepeatItem](#repeatitem)\<T\> | Yes| Repeat items.|
53
54### key
55
56key(keyGenerator: (item: T, index: number) => string): RepeatAttribute\<T\>
57
58Key generator.
59
60**Widget capability**: This API can be used in ArkTS widgets since API version 12.
61
62**Atomic service API**: This API can be used in atomic services since API version 12.
63
64**System capability**: SystemCapability.ArkUI.ArkUI.Full
65
66**Parameters**
67
68| Name| Type  | Mandatory| Description |
69| ------ | ---------- | -------- | -------- |
70| item  | T | Yes| Data item in the **arr** array.|
71| index  | number | Yes| Index of a data item in the **arr** array.|
72
73### virtualScroll
74
75virtualScroll(virtualScrollOptions?: VirtualScrollOptions): RepeatAttribute\<T\>
76
77Enables virtual scrolling for the **Repeat** component.
78
79**Widget capability**: This API can be used in ArkTS widgets since API version 12.
80
81**Atomic service API**: This API can be used in atomic services since API version 12.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85**Parameters**
86
87| Name| Type  | Mandatory| Description |
88| ------ | ---------- | -------- | -------- |
89| virtualScrollOptions  | [VirtualScrollOptions](#virtualscrolloptions)  | No| Virtual scrolling configuration.|
90
91### template
92
93template(type: string, itemBuilder: RepeatItemBuilder\<T\>, templateOptions?: TemplateOptions): RepeatAttribute\<T\>
94
95Defines a template for reusing.
96
97**Widget capability**: This API can be used in ArkTS widgets since API version 12.
98
99**Atomic service API**: This API can be used in atomic services since API version 12.
100
101**System capability**: SystemCapability.ArkUI.ArkUI.Full
102
103**Parameters**
104
105| Name| Type  | Mandatory| Description |
106| ------ | ---------- | -------- | -------- |
107| type | string | Yes| Template type.|
108| itemBuilder  | [RepeatItemBuilder](#repeatitembuilder)\<T\> | Yes| Component generator.|
109| templateOptions | [TemplateOptions](#templateoptions) | No| Template configuration.|
110
111### templateId
112
113templateId(typedFunc: TemplateTypedFunc\<T\>): RepeatAttribute\<T\>
114
115Assigns a template ID to this data item.
116
117**Widget capability**: This API can be used in ArkTS widgets since API version 12.
118
119**Atomic service API**: This API can be used in atomic services since API version 12.
120
121**System capability**: SystemCapability.ArkUI.ArkUI.Full
122
123**Parameters**
124
125| Name| Type  | Mandatory| Description |
126| ------ | ---------- | -------- | -------- |
127| typedFunc | [TemplateTypedFunc](#templatetypedfunc)\<T\> | Yes| Template ID to assign.|
128
129## RepeatItem
130
131**Widget capability**: This API can be used in ArkTS widgets since API version 12.
132
133**Atomic service API**: This API can be used in atomic services since API version 12.
134
135**System capability**: SystemCapability.ArkUI.ArkUI.Full
136
137**Parameters**
138
139| Name| Type  | Mandatory| Description                                        |
140| ------ | ------ | ---- | -------------------------------------------- |
141| item   | T      | Yes  | Each data item in **arr**. **T** indicates the data type passed in.|
142| index  | number | Yes  | Index corresponding to the current data item.                      |
143
144## VirtualScrollOptions
145
146**Widget capability**: This API can be used in ArkTS widgets since API version 12.
147
148**Atomic service API**: This API can be used in atomic services since API version 12.
149
150**System capability**: SystemCapability.ArkUI.ArkUI.Full
151
152**Parameters**
153
154| Name    | Type  | Mandatory| Description                                                        |
155| ---------- | ------ | ---- | ------------------------------------------------------------ |
156| totalCount | number | No  | Total length of the data source, which can be greater than the number of loaded data items.<br>With **arr.length** representing the length of the data source, the following are the rules for determining **totalCount**:<br>1. If **totalCount** is not set \|\| **totalCount** is not an integer \|\| totalCount <= 0 \|\| totalCount == arr.length, then **totalCount** is the length of the data source, and the list scrolls properly.<br>2. If 0 < **totalCount** < arr.length, only the **totalCount**-specified number of data items are rendered in the UI.<br>3. If **totalCount** > **arr.Length**, the scrollbar displays normally, but the areas without data items show up as empty spaces. When the scrolling animation finishes, the scrollbar rests at the position of the last data item. In this way, you can use the correct scrollbar style without requesting all the data at the same time.|
157
158> **NOTE**<br>When **totalCount** < **arr.length**, you are advised to set **totalCount** to a value that can fill the parent component to prevent any empty spaces within the parent component, which could lead to a suboptimal user experience.
159
160## RepeatItemBuilder
161
162type RepeatItemBuilder\<T\> = (repeatItem: RepeatItem\<T\>) => void
163
164**Widget capability**: This API can be used in ArkTS widgets since API version 12.
165
166**Atomic service API**: This API can be used in atomic services since API version 12.
167
168**System capability**: SystemCapability.ArkUI.ArkUI.Full
169
170**Parameters**
171
172| Name    | Type         | Mandatory     | Description                                   |
173| ---------- | ------------- | --------------------------------------- | --------------------------------------- |
174| repeatItem | [RepeatItem](#repeatitem)\<T\> | Yes| A state variable that combines **item** and **index**.|
175
176## TemplateOptions
177
178**Widget capability**: This API can be used in ArkTS widgets since API version 12.
179
180**Atomic service API**: This API can be used in atomic services since API version 12.
181
182**System capability**: SystemCapability.ArkUI.ArkUI.Full
183
184**Parameters**
185
186| Name     | Type  | Mandatory| Description                                                        |
187| ----------- | ------ | ---- | ------------------------------------------------------------ |
188| cachedCount | number | No  | Maximum number of child nodes of the current template that can be cached in the **Repeat** cache pool. This parameter takes effect only when **virtualScroll** is enabled.<br>When **cachedCount** is set to the maximum number of nodes of the current template that may appear on the screen, **Repeat** can be reused as much as possible. However, when there is no node of the current template on the screen, the cache pool is not released and the application memory increases. You need to set the configuration based on the actual situation.<br>If you do not specify **cachedCount**, the framework calculates **cachedCount** for different templates based on the number of visible and pre-rendered nodes on the screen. When the number of visible and pre-rendered nodes on the screen increases, **cachedCount** will also increase accordingly. It should be noted that the value of **cachedCount** will not decrease.<br> To explicitly specify **cachedCount**, you are advised to set it to the same as the number of nodes on the screen. Yet, setting **cachedCount** to less than 2 is not advised. Doing so may lead to the creation of new nodes during rapid scrolling, which could result in performance degradation.|
189
190## TemplateTypedFunc
191
192type TemplateTypedFunc\<T\> = (item : T, index : number) => string
193
194**Widget capability**: This API can be used in ArkTS widgets since API version 12.
195
196**Atomic service API**: This API can be used in atomic services since API version 12.
197
198**System capability**: SystemCapability.ArkUI.ArkUI.Full
199
200**Parameters**
201
202| Name| Type  | Mandatory| Description                                        |
203| ------ | ------ | ---- | -------------------------------------------- |
204| item   | T      | Yes  | Each data item in **arr**. **T** indicates the data type passed in.|
205| index  | number | Yes  | Index corresponding to the current data item.                      |
206