1# Repeat 2 3> **NOTE** 4> 5> 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. 6 7**Repeat** is used to perform repeated rendering based on array data. Generally, it is used together with container components. 8This document provides API parameter descriptions. For details about the development, see [Repeat: Reusing Child Components](../../../quick-start/arkts-new-rendering-control-repeat.md). 9 10## APIs 11 12### Repeat: \<T\>(arr: Array\<T\>) 13 14When **virtualScroll** is not enabled: renders repeated components based on the data source. This API must be used in conjunction with a container component. In addition, the component returned by the API must be a child component that can be contained in the **Repeat** parent container component. Compared to **ForEach**, **Repeat** optimizes the rendering performance for partial updates. The index for the component generator function is maintained by the framework. 15 16When virtualScroll is enabled: Iterates data from the provided data source as required and creates the corresponding component during each iteration. In this scenario, the API must be used together with a scrollable container component. When **Repeat** is used in a scrollable container component, the framework creates components as required based on the visible area of the container. When a component scrolls out of the visible area, the framework caches it and reuses it in the next iteration. 17 18**Widget capability**: This API can be used in ArkTS widgets since API version 12. 19 20**Atomic service API**: This API can be used in atomic services since API version 12. 21 22**System capability**: SystemCapability.ArkUI.ArkUI.Full 23 24**Parameters** 25 26| Name| Type | Mandatory| Description | 27| ------ | ---------- | -------- | -------- | 28| arr | Array\<T\> | Yes| Data source, which is an array of the **Array\<T>** type. You can determine the data types.| 29 30**Example** 31```ts 32// arr is an array of the Array<string> type, which is used as the data source for Repeat. 33Repeat<string>(this.arr) 34``` 35 36### Repeat: \<T\>(arr: RepeatArray\<T\>)<sup>18+</sup> 37 38> **NOTE** 39> 40> Data sources of the RepeatArray type are supported since API version 18. 41 42**Widget capability**: This API can be used in ArkTS widgets since API version 18. 43 44**Atomic service API**: This API can be used in atomic services since API version 18. 45 46**System capability**: SystemCapability.ArkUI.ArkUI.Full 47 48**Parameters** 49 50| Name| Type | Mandatory| Description | 51| ------ | ---------- | -------- | -------- | 52| arr | [RepeatArray\<T\>](#repeatarrayt18) | Yes| Data source, which is an array of the **RepeatArray\<T>** type. You can determine the data types.| 53 54## Events 55 56**Widget capability**: This API can be used in ArkTS widgets since API version 12. 57 58**Atomic service API**: This API can be used in atomic services since API version 12. 59 60**System capability**: SystemCapability.ArkUI.ArkUI.Full 61 62### each 63 64each(itemGenerator: (repeatItem: RepeatItem\<T\>) => void): RepeatAttribute\<T\> 65 66Generates components. This function is used as the default generator when data items do not match any specified template or template ID. 67 68> **NOTE** 69> 70> The **each** attribute is mandatory. Otherwise, a runtime error occurs. 71> The **itemGenerator** parameter is of the **RepeatItem** type, which combines **item** and **index**. Do not split **RepeatItem**. 72 73**Widget capability**: This API can be used in ArkTS widgets since API version 12. 74 75**Atomic service API**: This API can be used in atomic services since API version 12. 76 77**System capability**: SystemCapability.ArkUI.ArkUI.Full 78 79**Parameters** 80 81| Name| Type | Mandatory| Description| 82| ------ | ---------- | -------- | -------- | 83| repeatItem | [RepeatItem](#repeatitemt)\<T\> | Yes| Data item for the repeat.| 84 85**Example** 86```ts 87// Create a Text component for each item in the arr array of the Array<string> type. 88Repeat<string>(this.arr) 89 .each((obj: RepeatItem<string>) => { Text(obj.item) }) 90``` 91 92### key 93 94key(keyGenerator: (item: T, index: number) => string): RepeatAttribute\<T\> 95 96Generates a unique key for each item in the data source. 97 98**Widget capability**: This API can be used in ArkTS widgets since API version 12. 99 100**Atomic service API**: This API can be used in atomic services since API version 12. 101 102**System capability**: SystemCapability.ArkUI.ArkUI.Full 103 104**Parameters** 105 106| Name| Type | Mandatory| Description | 107| ------ | ---------- | -------- | -------- | 108| item | T | Yes| Data item in the **arr** array.| 109| index | number | Yes| Index of the data item in the **arr** array.| 110 111**Example** 112```ts 113// Create a Text component for each item in the arr array of the Array<string> type. 114// Use the string value as the key value. 115Repeat<string>(this.arr) 116 .each((obj: RepeatItem<string>) => { Text(obj.item) }) 117 .key((obj: string) => obj) 118``` 119 120### virtualScroll 121 122virtualScroll(virtualScrollOptions?: VirtualScrollOptions): RepeatAttribute\<T\> 123 124Enables virtual scrolling for the **Repeat** component. 125 126**Atomic service API**: This API can be used in atomic services since API version 12. 127 128**System capability**: SystemCapability.ArkUI.ArkUI.Full 129 130**Parameters** 131 132| Name| Type | Mandatory| Description | 133| ------ | ---------- | -------- | -------- | 134| virtualScrollOptions | [VirtualScrollOptions](#virtualscrolloptions) | No| Virtual scrolling configuration.| 135 136**Example** 137```ts 138// Create a Text component for each item in the arr array of the Array<string> type. 139// Use Repeat in a List container component with virtual scrolling enabled. 140List() { 141 Repeat<string>(this.arr) 142 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 143 .virtualScroll() 144} 145``` 146 147### template 148 149template(type: string, itemBuilder: RepeatItemBuilder\<T\>, templateOptions?: TemplateOptions): RepeatAttribute\<T\> 150 151Defines a reusable template for component generation. 152 153**Atomic service API**: This API can be used in atomic services since API version 12. 154 155**System capability**: SystemCapability.ArkUI.ArkUI.Full 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | ---------- | -------- | -------- | 161| type | string | Yes| Type of the template.| 162| itemBuilder | [RepeatItemBuilder](#repeatitembuildert)\<T\> | Yes| Component generator.| 163| templateOptions | [TemplateOptions](#templateoptions) | No| Configuration of the template.| 164 165**Example** 166```ts 167// arr is an array of the Array<string> type. 168// Use Repeat in a List container component with virtual scrolling enabled. 169// Define a reusable template temp for generating Text components. 170List() { 171 Repeat<string>(this.arr) 172 .each((obj: RepeatItem<string>) => {}) 173 .virtualScroll() 174 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 175} 176``` 177 178### templateId 179 180templateId(typedFunc: TemplateTypedFunc\<T\>): RepeatAttribute\<T\> 181 182Assigns a template ID to each data item. 183 184**Atomic service API**: This API can be used in atomic services since API version 12. 185 186**System capability**: SystemCapability.ArkUI.ArkUI.Full 187 188**Parameters** 189 190| Name| Type | Mandatory| Description | 191| ------ | ---------- | -------- | -------- | 192| typedFunc | [TemplateTypedFunc](#templatetypedfunct)\<T\> | Yes| Function that generates a template ID for each data item.| 193 194**Example** 195```ts 196// arr is an array of the Array<string> type. 197// Use Repeat in a List container component with virtual scrolling enabled. 198// Define a reusable template temp for generating Text components. 199// Use the temp template for all data items. 200List() { 201 Repeat<string>(this.arr) 202 .each((obj: RepeatItem<string>) => {}) 203 .virtualScroll() 204 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 205 .templateId((item: string, index: number) => { return 'temp' }) 206} 207``` 208 209## Properties 210 211Inherited from [DynamicNode](./ts-rendering-control-foreach.md#dynamicnode12) since API version 18. 212 213## RepeatArray\<T\><sup>18+</sup> 214 215type RepeatArray\<T\> = Array\<T\> | ReadonlyArray\<T\> | Readonly\<Array\<T\>\> 216 217Defines a union type for the **Repeat** data source parameter. 218 219**Widget capability**: This API can be used in ArkTS widgets since API version 18. 220 221**Atomic service API**: This API can be used in atomic services since API version 18. 222 223**System capability**: SystemCapability.ArkUI.ArkUI.Full 224 225| Type | Description | 226| -------- | -------- | 227| Array\<T\> | Regular array type.| 228| ReadonlyArray\<T\> | Read-only array type, where the array object cannot be modified.| 229| Readonly\<Array\<T\>> | Read-only array type, where the array object cannot be modified.| 230 231## RepeatItem\<T\> 232 233**Widget capability**: This API can be used in ArkTS widgets since API version 12. 234 235**Atomic service API**: This API can be used in atomic services since API version 12. 236 237**System capability**: SystemCapability.ArkUI.ArkUI.Full 238 239| Name| Type | Mandatory| Description | 240| ------ | ------ | ---- | -------------------------------------------- | 241| item | T | Yes | Each data item in the **arr** array. **T** indicates the data type passed in.| 242| index | number | Yes | Index corresponding to the current data item. | 243 244## VirtualScrollOptions 245 246**Atomic service API**: This API can be used in atomic services since API version 12. 247 248**System capability**: SystemCapability.ArkUI.ArkUI.Full 249 250| Name | Type | Mandatory| Description | 251| ---------- | ------ | ---- | ------------------------------------------------------------ | 252| totalCount | number | No | Total number of data items to load, which may not equal the data source length.| 253| reusable<sup>18+</sup> | boolean | No | Whether to enable component reuse. The value **true** means to enable component reuse, and **false** means the opposite.<br>Default value: **false**| 254| onLazyLoading<sup>18+</sup> | (index: number) => void | No | Function to load data on demand for a given index.| 255| onTotalCount<sup>18+</sup> | () => number | No | Function to dynamically obtain the total number of items, which may not equal the data source length. Prioritize this function over **totalCount**. If both **totalCount** and **onTotalCount** are set, **totalCount** is ignored.| 256 257**Example** 258```ts 259// Create a Text component for each item in the arr array. Use Repeat in a List container component with virtual scrolling enabled. 260// Set the total number of data items to the length of the data source and enable component reuse. 261List() { 262 Repeat<string>(this.arr) 263 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 264 .virtualScroll( { totalCount: this.arr.length, reusable: true } ) 265} 266 267// Assume that the total number of items is 100, and 3 items are needed for the initial screen rendering. 268// The initial array provides the first 3 items (arr = ['No.0', 'No.1', 'No.2']), and lazy loading is enabled. 269List() { 270 Repeat<string>(this.arr) 271 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 272 .virtualScroll( { 273 onTotalCount: () => { return 100; }, 274 onLazyLoading: (index: number) => { this.arr[index] = `No.${index}`; } 275 } ) 276} 277``` 278 279## RepeatItemBuilder\<T\> 280 281type RepeatItemBuilder\<T\> = (repeatItem: RepeatItem\<T\>) => void 282 283**Atomic service API**: This API can be used in atomic services since API version 12. 284 285**System capability**: SystemCapability.ArkUI.ArkUI.Full 286 287**Parameters** 288 289| Name | Type | Mandatory | Description | 290| ---------- | ------------- | --------------------------------------- | --------------------------------------- | 291| repeatItem | [RepeatItem](#repeatitemt)\<T\> | Yes| A state variable that combines **item** and **index**.| 292 293## TemplateOptions 294 295**Atomic service API**: This API can be used in atomic services since API version 12. 296 297**System capability**: SystemCapability.ArkUI.ArkUI.Full 298 299| Name | Type | Mandatory| Description | 300| ----------- | ------ | ---- | ------------------------------------------------------------ | 301| cachedCount | number | No | Maximum number of child nodes that can be cached for the current template in the **Repeat** cache pool. This parameter takes effect only when **virtualScroll** is enabled.| 302 303**Example** 304```ts 305// Create a Text component for each item in the arr array. Use Repeat in a List container component with virtual scrolling enabled. 306// Define a reusable template temp for generating Text components. Use the temp template for all data items. 307// Set the maximum cache count for the temp template to 2. 308List() { 309 Repeat<string>(this.arr) 310 .each((obj: RepeatItem<string>) => {}) 311 .virtualScroll() 312 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}, { cachedCount: 2 }) 313 .templateId((item: string, index: number) => { return 'temp' }) 314} 315``` 316 317## TemplateTypedFunc\<T\> 318 319type TemplateTypedFunc\<T\> = (item : T, index : number) => string 320 321**Atomic service API**: This API can be used in atomic services since API version 12. 322 323**System capability**: SystemCapability.ArkUI.ArkUI.Full 324 325**Parameters** 326 327| Name| Type | Mandatory| Description | 328| ------ | ------ | ---- | -------------------------------------------- | 329| item | T | Yes | Each data item in the **arr** array. **T** indicates the data type passed in.| 330| index | number | Yes | Index corresponding to the current data item. | 331