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** enables rendering of repeated content based on array type data.<br> 8It must be used in a container component. This 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 12Repeat: \<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## Events 37 38**Widget capability**: This API can be used in ArkTS widgets since API version 12. 39 40**Atomic service API**: This API can be used in atomic services since API version 12. 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44### each 45 46each(itemGenerator: (repeatItem: RepeatItem\<T\>) => void): RepeatAttribute\<T\> 47 48Component generator function. This function is used as the default generator when data items do not match any specified template or template ID. 49 50> **NOTE** 51> 52> The **each** attribute is mandatory. Otherwise, a runtime error occurs. 53> The **itemGenerator** parameter is of the **RepeatItem** type, which combines **item** and **index**. Do not split **RepeatItem**. 54 55**Widget capability**: This API can be used in ArkTS widgets since API version 12. 56 57**Atomic service API**: This API can be used in atomic services since API version 12. 58 59**System capability**: SystemCapability.ArkUI.ArkUI.Full 60 61**Parameters** 62 63| Name| Type | Mandatory| Description| 64| ------ | ---------- | -------- | -------- | 65| repeatItem | [RepeatItem](#repeatitemt)\<T\> | Yes| Data item for the repeat.| 66 67**Example** 68```ts 69// Create a Text component for each item in the arr array of the Array<string> type. 70Repeat<string>(this.arr) 71 .each((obj: RepeatItem<string>) => { Text(obj.item) }) 72``` 73 74### key 75 76key(keyGenerator: (item: T, index: number) => string): RepeatAttribute\<T\> 77 78Generates a unique key for each item in the data source. 79 80**Widget capability**: This API can be used in ArkTS widgets since API version 12. 81 82**Atomic service API**: This API can be used in atomic services since API version 12. 83 84**System capability**: SystemCapability.ArkUI.ArkUI.Full 85 86**Parameters** 87 88| Name| Type | Mandatory| Description | 89| ------ | ---------- | -------- | -------- | 90| item | T | Yes| Data item in the **arr** array.| 91| index | number | Yes| Index of the data item in the **arr** array.| 92 93**Example** 94```ts 95// Create a Text component for each item in the arr array of the Array<string> type. 96// Use the string value as the key value. 97Repeat<string>(this.arr) 98 .each((obj: RepeatItem<string>) => { Text(obj.item) }) 99 .key((obj: string) => obj) 100``` 101 102### virtualScroll 103 104virtualScroll(virtualScrollOptions?: VirtualScrollOptions): RepeatAttribute\<T\> 105 106Enables virtual scrolling for the **Repeat** component. 107 108**Atomic service API**: This API can be used in atomic services since API version 12. 109 110**System capability**: SystemCapability.ArkUI.ArkUI.Full 111 112**Parameters** 113 114| Name| Type | Mandatory| Description | 115| ------ | ---------- | -------- | -------- | 116| virtualScrollOptions | [VirtualScrollOptions](#virtualscrolloptions) | No| Virtual scrolling configuration.| 117 118**Example** 119```ts 120// Create a Text component for each item in the arr array of the Array<string> type. 121// Use Repeat in a List container component with virtual scrolling enabled. 122List() { 123 Repeat<string>(this.arr) 124 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 125 .virtualScroll() 126} 127``` 128 129### template 130 131template(type: string, itemBuilder: RepeatItemBuilder\<T\>, templateOptions?: TemplateOptions): RepeatAttribute\<T\> 132 133Defines a reusable template for component generation. 134 135**Atomic service API**: This API can be used in atomic services since API version 12. 136 137**System capability**: SystemCapability.ArkUI.ArkUI.Full 138 139**Parameters** 140 141| Name| Type | Mandatory| Description | 142| ------ | ---------- | -------- | -------- | 143| type | string | Yes| Type of the template.| 144| itemBuilder | [RepeatItemBuilder](#repeatitembuildert)\<T\> | Yes| Component generator.| 145| templateOptions | [TemplateOptions](#templateoptions) | No| Configuration of the template.| 146 147**Example** 148```ts 149// arr is an array of the Array<string> type. 150// Use Repeat in a List container component with virtual scrolling enabled. 151// Define a reusable template temp for generating Text components. 152List() { 153 Repeat<string>(this.arr) 154 .each((obj: RepeatItem<string>) => {}) 155 .virtualScroll() 156 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 157} 158``` 159 160### templateId 161 162templateId(typedFunc: TemplateTypedFunc\<T\>): RepeatAttribute\<T\> 163 164Assigns a template ID to each data item. 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| typedFunc | [TemplateTypedFunc](#templatetypedfunct)\<T\> | Yes| Function that generates a template ID for each data item.| 175 176**Example** 177```ts 178// arr is an array of the Array<string> type. 179// Use Repeat in a List container component with virtual scrolling enabled. 180// Define a reusable template temp for generating Text components. 181// Use the temp template for all data items. 182List() { 183 Repeat<string>(this.arr) 184 .each((obj: RepeatItem<string>) => {}) 185 .virtualScroll() 186 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 187 .templateId((item: string, index: number) => { return 'temp' }) 188} 189``` 190 191## RepeatItem\<T\> 192 193**Widget capability**: This API can be used in ArkTS widgets since API version 12. 194 195**Atomic service API**: This API can be used in atomic services since API version 12. 196 197**System capability**: SystemCapability.ArkUI.ArkUI.Full 198 199| Name| Type | Mandatory| Description | 200| ------ | ------ | ---- | -------------------------------------------- | 201| item | T | Yes | Each data item in the **arr** array. **T** indicates the data type passed in.| 202| index | number | Yes | Index corresponding to the current data item. | 203 204## VirtualScrollOptions 205 206**Atomic service API**: This API can be used in atomic services since API version 12. 207 208**System capability**: SystemCapability.ArkUI.ArkUI.Full 209 210| Name | Type | Mandatory| Description | 211| ---------- | ------ | ---- | ------------------------------------------------------------ | 212| totalCount | number | No | Total number of data items to load, which can be greater than or less than the data source length.| 213 214**Example** 215```ts 216// Create a Text component for each item in the arr array. Use Repeat in a List container component with virtual scrolling enabled. 217// Set the total number of data items to the length of the data source and enable component reuse. 218List() { 219 Repeat<string>(this.arr) 220 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 221 .virtualScroll( { totalCount: this.arr.length, reusable: true } ) 222} 223``` 224 225## RepeatItemBuilder\<T\> 226 227type RepeatItemBuilder\<T\> = (repeatItem: RepeatItem\<T\>) => void 228 229**Atomic service API**: This API can be used in atomic services since API version 12. 230 231**System capability**: SystemCapability.ArkUI.ArkUI.Full 232 233**Parameters** 234 235| Name | Type | Mandatory | Description | 236| ---------- | ------------- | --------------------------------------- | --------------------------------------- | 237| repeatItem | [RepeatItem](#repeatitemt)\<T\> | Yes| A state variable that combines **item** and **index**.| 238 239## TemplateOptions 240 241**Atomic service API**: This API can be used in atomic services since API version 12. 242 243**System capability**: SystemCapability.ArkUI.ArkUI.Full 244 245| Name | Type | Mandatory| Description | 246| ----------- | ------ | ---- | ------------------------------------------------------------ | 247| 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.| 248 249**Example** 250```ts 251// Create a Text component for each item in the arr array. Use Repeat in a List container component with virtual scrolling enabled. 252// Define a reusable template temp for generating Text components. Use the temp template for all data items. 253// Set the maximum cache count for the temp template to 2. 254List() { 255 Repeat<string>(this.arr) 256 .each((obj: RepeatItem<string>) => {}) 257 .virtualScroll() 258 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}, { cachedCount: 2 }) 259 .templateId((item: string, index: number) => { return 'temp' }) 260} 261``` 262 263## TemplateTypedFunc\<T\> 264 265type TemplateTypedFunc\<T\> = (item : T, index : number) => string 266 267**Atomic service API**: This API can be used in atomic services since API version 12. 268 269**System capability**: SystemCapability.ArkUI.ArkUI.Full 270 271**Parameters** 272 273| Name| Type | Mandatory| Description | 274| ------ | ------ | ---- | -------------------------------------------- | 275| item | T | Yes | Each data item in **arr**. **T** indicates the data type passed in.| 276| index | number | Yes | Index corresponding to the current data item. | 277