1# Repeat 2 3> **说明：** 4> 5> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6 7Repeat基于数组类型数据来进行循环渲染，一般与容器组件配合使用。 8本文档仅为API参数说明。开发者指南见：[Repeat开发者指南](../../../ui/state-management/arkts-new-rendering-control-repeat.md)。 9 10## 接口 11 12### Repeat: \<T\>(arr: Array\<T\>) 13 14Repeat组件non-virtualScroll场景（不开启virtualScroll开关）中，Repeat基于数据源进行循环渲染，需要与容器组件配合使用，且接口返回的组件应当是允许包含在Repeat父容器组件中的子组件。Repeat循环渲染和ForEach相比有两个区别，一是优化了部分更新场景下的渲染性能，二是组件生成函数的索引index由框架侧来维护。 15 16Repeat组件virtualScroll场景中，Repeat将从提供的数据源中按需迭代数据，并在每次迭代过程中创建相应的组件，必须与滚动类容器组件配合使用。当在滚动类容器组件中使用了Repeat，框架会根据滚动容器可视区域按需创建组件，当组件滑出可视区域外时，框架会缓存组件，并在下一次迭代中使用。 17 18**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 19 20**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 21 22**系统能力：** SystemCapability.ArkUI.ArkUI.Full 23 24**参数：** 25 26| 参数名 | 类型 | 必填 | 说明 | 27| ------ | ---------- | -------- | -------- | 28| arr | Array\<T\> | 是 | 数据源，为`Array<T>`类型的数组，由开发者决定数据类型。 | 29 30**示例：** 31```ts 32// arr是Array<string>类型的数组，以arr为数据源创建Repeat组件 33Repeat<string>(this.arr) 34``` 35 36### Repeat: \<T\>(arr: RepeatArray\<T\>)<sup>18+</sup> 37 38> **说明：** 39> 40> 从API version 18开始，Repeat数据源参数支持RepeatArray类型。 41 42**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 43 44**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 45 46**系统能力：** SystemCapability.ArkUI.ArkUI.Full 47 48**参数：** 49 50| 参数名 | 类型 | 必填 | 说明 | 51| ------ | ---------- | -------- | -------- | 52| arr | [RepeatArray\<T\>](#repeatarrayt18) | 是 | 数据源，为`RepeatArray<T>`类型的数组，由开发者决定数据类型。 | 53 54## 事件 55 56**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 57 58**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 59 60**系统能力：** SystemCapability.ArkUI.ArkUI.Full 61 62### each 63 64each(itemGenerator: (repeatItem: RepeatItem\<T\>) => void): RepeatAttribute\<T\> 65 66组件生成函数。template和templateId匹配不上的数据项走默认生成函数each。 67 68> **说明** 69> 70> `each`属性必须有，否则运行时会报错。 71> `itemGenerator`的参数为`RepeatItem`，该参数将`item`和`index`结合到了一起，请勿将`RepeatItem`参数拆开使用。 72 73**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 74 75**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79**参数：** 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ------ | ---------- | -------- | -------- | 83| repeatItem | [RepeatItem](#repeatitemt)\<T\> | 是 | repeat数据项。 | 84 85**示例：** 86```ts 87// arr是Array<string>类型的数组，为每个数据创建一个Text组件 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 96键值生成函数。 97 98**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 99 100**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 101 102**系统能力：** SystemCapability.ArkUI.ArkUI.Full 103 104**参数：** 105 106| 参数名 | 类型 | 必填 | 说明 | 107| ------ | ---------- | -------- | -------- | 108| item | T | 是 | `arr`数组中的数据项。 | 109| index | number | 是 | `arr`数组中的数据项索引。 | 110 111**示例：** 112```ts 113// arr是Array<string>类型的数组，为每个数据创建一个Text组件 114// 并将字符串的值作为其键值 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 124`Repeat`开启虚拟滚动。 125 126**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| ------ | ---------- | -------- | -------- | 134| virtualScrollOptions | [VirtualScrollOptions](#virtualscrolloptions对象说明) | 否 | 虚拟滚动配置项。 | 135 136**示例：** 137```ts 138// arr是Array<string>类型的数组，为每个数据创建一个Text组件 139// 在List容器组件中使用Repeat，并打开virtualScroll 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 151复用模板。 152 153**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 154 155**系统能力：** SystemCapability.ArkUI.ArkUI.Full 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| ------ | ---------- | -------- | -------- | 161| type | string | 是 | 当前模板类型。 | 162| itemBuilder | [RepeatItemBuilder](#repeatitembuildert)\<T\> | 是 | 组件生成函数。 | 163| templateOptions | [TemplateOptions](#templateoptions对象说明) | 否 | 当前模板配置项。 | 164 165**示例：** 166```ts 167// arr是Array<string>类型的数组 168// 在List容器组件中使用Repeat，并打开virtualScroll 169// 创建模板temp，该模板为数据创建Text组件 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 182为当前数据项分配templateId。 183 184**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 185 186**系统能力：** SystemCapability.ArkUI.ArkUI.Full 187 188**参数：** 189 190| 参数名 | 类型 | 必填 | 说明 | 191| ------ | ---------- | -------- | -------- | 192| typedFunc | [TemplateTypedFunc](#templatetypedfunct)\<T\> | 是 | 生成当前数据项对应的templateId。 | 193 194**示例：** 195```ts 196// arr是Array<string>类型的数组 197// 在List容器组件中使用Repeat，并打开virtualScroll 198// 创建模板temp，该模板为数据创建Text组件 199// 所有数据项都使用temp模板 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## 属性 210 211从API version 18开始，继承自[DynamicNode](./ts-rendering-control-foreach.md#dynamicnode12)。 212 213## RepeatArray\<T\><sup>18+</sup> 214 215type RepeatArray\<T\> = Array\<T\> | ReadonlyArray\<T\> | Readonly\<Array\<T\>\> 216 217Repeat数据源参数联合类型。 218 219**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 220 221**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 222 223**系统能力：** SystemCapability.ArkUI.ArkUI.Full 224 225| 类型 | 说明 | 226| -------- | -------- | 227| Array\<T\> | 常规数组类型。 | 228| ReadonlyArray\<T\> | 只读数组类型，不允许数组对象变更。 | 229| Readonly\<Array\<T\>> | 只读数组类型，不允许数组对象变更。 | 230 231## RepeatItem\<T\> 232 233**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 234 235**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239| 名称 | 类型 | 必填 | 说明 | 240| ------ | ------ | ---- | -------------------------------------------- | 241| item | T | 是 | arr中每一个数据项。T为开发者传入的数据类型。 | 242| index | number | 是 | 当前数据项对应的索引。 | 243 244## VirtualScrollOptions对象说明 245 246**系统能力：** SystemCapability.ArkUI.ArkUI.Full 247 248| 名称 | 类型 | 必填 | 说明 | 249| ---------- | ------ | ---- | ------------------------------------------------------------ | 250| totalCount | number | 否 | 加载的数据项总数，可以不等于数据源长度。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 251| reusable<sup>18+</sup> | boolean | 否 | 是否开启复用功能，true表示开启，false表示不开启，默认开启。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 252| onLazyLoading<sup>18+</sup> | (index: number) => void | 否 | 数据懒加载函数，向指定的数据源index中写入数据。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 253| onTotalCount<sup>18+</sup> | () => number | 否 | 数据项总数计算函数，返回值可以不等于数据源长度。推荐使用onTotalCount代替totalCount。同时设置totalCount与onTotalCount时，忽略totalCount。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 254 255**示例：** 256```ts 257// arr是Array<string>类型的数组，在List容器组件中使用Repeat，并打开virtualScroll 258// 将加载的数据项总数设为数据源的长度，并开启复用功能 259List() { 260 Repeat<string>(this.arr) 261 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 262 .virtualScroll( { totalCount: this.arr.length, reusable: true } ) 263} 264 265// 假设数据项总数为100，首屏渲染需3项数据 266// 初始数组提供前3项数据（arr = ['No.0', 'No.1', 'No.2']），并开启数据懒加载功能 267List() { 268 Repeat<string>(this.arr) 269 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 270 .virtualScroll( { 271 onTotalCount: () => { return 100; }, 272 onLazyLoading: (index: number) => { this.arr[index] = `No.${index}`; } 273 } ) 274} 275``` 276 277## RepeatItemBuilder\<T\> 278 279type RepeatItemBuilder\<T\> = (repeatItem: RepeatItem\<T\>) => void 280 281**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 282 283**系统能力：** SystemCapability.ArkUI.ArkUI.Full 284 285**参数：** 286 287| 参数名 | 类型 | 必填 | 说明 | 288| ---------- | ------------- | --------------------------------------- | --------------------------------------- | 289| repeatItem | [RepeatItem](#repeatitemt)\<T\> | 是 | 将item和index结合到一起的一个状态变量。 | 290 291## TemplateOptions对象说明 292 293**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 294 295**系统能力：** SystemCapability.ArkUI.ArkUI.Full 296 297| 名称 | 类型 | 必填 | 说明 | 298| ----------- | ------ | ---- | ------------------------------------------------------------ | 299| cachedCount | number | 否 | 当前模板在Repeat的缓存池中可缓存子节点的最大数量，仅在开启virtualScroll后生效。 | 300 301**示例：** 302```ts 303// arr是Array<string>类型的数组，在List容器组件中使用Repeat，并打开virtualScroll 304// 创建模板temp，该模板为数据创建Text组件，所有数据项都使用temp模板 305// 将temp模板的最大缓存节点数量设为2 306List() { 307 Repeat<string>(this.arr) 308 .each((obj: RepeatItem<string>) => {}) 309 .virtualScroll() 310 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}, { cachedCount: 2 }) 311 .templateId((item: string, index: number) => { return 'temp' }) 312} 313``` 314 315## TemplateTypedFunc\<T\> 316 317type TemplateTypedFunc\<T\> = (item : T, index : number) => string 318 319**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 320 321**系统能力：** SystemCapability.ArkUI.ArkUI.Full 322 323**参数：** 324 325| 参数名 | 类型 | 必填 | 说明 | 326| ------ | ------ | ---- | -------------------------------------------- | 327| item | T | 是 | arr中每一个数据项。T为开发者传入的数据类型。 | 328| index | number | 是 | 当前数据项对应的索引。 |