1# Repeat 2 3> **说明：** 4> 5> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6 7本文档仅为API参数说明。开发者指南见：[Repeat开发者指南](../../../quick-start/arkts-new-rendering-control-repeat.md) 8 9## 接口 10 11Repeat: \<T\>(arr: Array\<T\>) 12 13Repeat组件non-virtualScroll场景（不开启virtualScroll开关）中，Repeat基于数据源进行循环渲染，需要与容器组件配合使用，且接口返回的组件应当是允许包含在Repeat父容器组件中的子组件。Repeat循环渲染和ForEach相比有两个区别，一是优化了部分更新场景下的渲染性能，二是组件生成函数的索引index由框架侧来维护。 14 15Repeat组件virtualScroll场景中，Repeat将从提供的数据源中按需迭代数据，并在每次迭代过程中创建相应的组件，必须与滚动类容器组件配合使用。当在滚动类容器组件中使用了Repeat，框架会根据滚动容器可视区域按需创建组件，当组件滑出可视区域外时，框架会缓存组件，并在下一次迭代中使用。 16 17**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 18 19**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 20 21**系统能力：** SystemCapability.ArkUI.ArkUI.Full 22 23**参数：** 24 25| 参数名 | 类型 | 必填 | 说明 | 26| ------ | ---------- | -------- | -------- | 27| arr | Array\<T\> | 是 | 数据源，为`Array<T>`类型的数组，由开发者决定数据类型。 | 28 29**示例：** 30```ts 31// arr是Array<string>类型的数组，以arr为数据源创建Repeat组件 32Repeat<string>(this.arr) 33``` 34 35## 事件 36 37**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 38 39**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.ArkUI.ArkUI.Full 42 43### each 44 45each(itemGenerator: (repeatItem: RepeatItem\<T\>) => void): RepeatAttribute\<T\> 46 47组件生成函数。template和templateId匹配不上的数据项走默认生成函数each。 48 49> **说明** 50> 51> `each`属性必须有，否则运行时会报错。 52> `itemGenerator`的参数为`RepeatItem`，该参数将`item`和`index`结合到了一起，请勿将`RepeatItem`参数拆开使用。 53 54**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 55 56**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 57 58**系统能力：** SystemCapability.ArkUI.ArkUI.Full 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ---------- | -------- | -------- | 64| repeatItem | [RepeatItem](#repeatitemt)\<T\> | 是 | repeat数据项 | 65 66**示例：** 67```ts 68// arr是Array<string>类型的数组，为每个数据创建一个Text组件 69Repeat<string>(this.arr) 70 .each((obj: RepeatItem<string>) => { Text(obj.item) }) 71``` 72 73### key 74 75key(keyGenerator: (item: T, index: number) => string): RepeatAttribute\<T\> 76 77键值生成函数。 78 79**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 80 81**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 82 83**系统能力：** SystemCapability.ArkUI.ArkUI.Full 84 85**参数：** 86 87| 参数名 | 类型 | 必填 | 说明 | 88| ------ | ---------- | -------- | -------- | 89| item | T | 是 | `arr`数组中的数据项 | 90| index | number | 是 | `arr`数组中的数据项索引 | 91 92**示例：** 93```ts 94// arr是Array<string>类型的数组，为每个数据创建一个Text组件 95// 并将字符串的值作为其键值 96Repeat<string>(this.arr) 97 .each((obj: RepeatItem<string>) => { Text(obj.item) }) 98 .key((obj: string) => obj) 99``` 100 101### virtualScroll 102 103virtualScroll(virtualScrollOptions?: VirtualScrollOptions): RepeatAttribute\<T\> 104 105`Repeat`开启虚拟滚动。 106 107**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 108 109**系统能力：** SystemCapability.ArkUI.ArkUI.Full 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| ------ | ---------- | -------- | -------- | 115| virtualScrollOptions | [VirtualScrollOptions](#virtualscrolloptions对象说明) | 否 | 虚拟滚动配置项 | 116 117**示例：** 118```ts 119// arr是Array<string>类型的数组，为每个数据创建一个Text组件 120// 在List容器组件中使用Repeat，并打开virtualScroll 121List() { 122 Repeat<string>(this.arr) 123 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 124 .virtualScroll() 125} 126``` 127 128### template 129 130template(type: string, itemBuilder: RepeatItemBuilder\<T\>, templateOptions?: TemplateOptions): RepeatAttribute\<T\> 131 132复用模板。 133 134**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 135 136**系统能力：** SystemCapability.ArkUI.ArkUI.Full 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| ------ | ---------- | -------- | -------- | 142| type | string | 是 | 当前模板类型 | 143| itemBuilder | [RepeatItemBuilder](#repeatitembuildert)\<T\> | 是 | 组件生成函数 | 144| templateOptions | [TemplateOptions](#templateoptions对象说明) | 否 | 当前模板配置项 | 145 146**示例：** 147```ts 148// arr是Array<string>类型的数组 149// 在List容器组件中使用Repeat，并打开virtualScroll 150// 创建模板temp，该模板为数据创建Text组件 151List() { 152 Repeat<string>(this.arr) 153 .each((obj: RepeatItem<string>) => {}) 154 .virtualScroll() 155 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 156} 157``` 158 159### templateId 160 161templateId(typedFunc: TemplateTypedFunc\<T\>): RepeatAttribute\<T\> 162 163为当前数据项分配templateId。 164 165**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 166 167**系统能力：** SystemCapability.ArkUI.ArkUI.Full 168 169**参数：** 170 171| 参数名 | 类型 | 必填 | 说明 | 172| ------ | ---------- | -------- | -------- | 173| typedFunc | [TemplateTypedFunc](#templatetypedfunct)\<T\> | 是 | 生成当前数据项对应的templateId | 174 175**示例：** 176```ts 177// arr是Array<string>类型的数组 178// 在List容器组件中使用Repeat，并打开virtualScroll 179// 创建模板temp，该模板为数据创建Text组件 180// 所有数据项都使用temp模板 181List() { 182 Repeat<string>(this.arr) 183 .each((obj: RepeatItem<string>) => {}) 184 .virtualScroll() 185 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 186 .templateId((item: string, index: number) => { return 'temp' }) 187} 188``` 189 190## RepeatItem\<T\> 191 192**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 193 194**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 195 196**系统能力：** SystemCapability.ArkUI.ArkUI.Full 197 198| 名称 | 类型 | 必填 | 说明 | 199| ------ | ------ | ---- | -------------------------------------------- | 200| item | T | 是 | arr中每一个数据项。T为开发者传入的数据类型。 | 201| index | number | 是 | 当前数据项对应的索引。 | 202 203## VirtualScrollOptions对象说明 204 205**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 206 207**系统能力：** SystemCapability.ArkUI.ArkUI.Full 208 209| 名称 | 类型 | 必填 | 说明 | 210| ---------- | ------ | ---- | ------------------------------------------------------------ | 211| totalCount | number | 否 | 加载的数据项总数，可以大于/小于数据源长度 | 212 213**示例：** 214```ts 215// arr是Array<string>类型的数组，在List容器组件中使用Repeat，并打开virtualScroll 216// 将加载的数据项总数设为数据源的长度 217List() { 218 Repeat<string>(this.arr) 219 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 220 .virtualScroll( { totalCount: this.arr.length } ) 221} 222``` 223 224## RepeatItemBuilder\<T\> 225 226type RepeatItemBuilder\<T\> = (repeatItem: RepeatItem\<T\>) => void 227 228**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 229 230**系统能力：** SystemCapability.ArkUI.ArkUI.Full 231 232**参数：** 233 234| 参数名 | 类型 | 必填 | 说明 | 235| ---------- | ------------- | --------------------------------------- | --------------------------------------- | 236| repeatItem | [RepeatItem](#repeatitemt)\<T\> | 是 | 将item和index结合到一起的一个状态变量。 | 237 238## TemplateOptions对象说明 239 240**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 241 242**系统能力：** SystemCapability.ArkUI.ArkUI.Full 243 244| 名称 | 类型 | 必填 | 说明 | 245| ----------- | ------ | ---- | ------------------------------------------------------------ | 246| cachedCount | number | 否 | 当前模板在Repeat的缓存池中可缓存子节点的最大数量，仅在开启virtualScroll后生效。 | 247 248**示例：** 249```ts 250// arr是Array<string>类型的数组，在List容器组件中使用Repeat，并打开virtualScroll 251// 创建模板temp，该模板为数据创建Text组件，所有数据项都使用temp模板 252// 将temp模板的最大缓存节点数量设为2 253List() { 254 Repeat<string>(this.arr) 255 .each((obj: RepeatItem<string>) => {}) 256 .virtualScroll() 257 .template('temp', (obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}, { cachedCount: 2 }) 258 .templateId((item: string, index: number) => { return 'temp' }) 259} 260``` 261 262## TemplateTypedFunc\<T\> 263 264type TemplateTypedFunc\<T\> = (item : T, index : number) => string 265 266**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 267 268**系统能力：** SystemCapability.ArkUI.ArkUI.Full 269 270**参数：** 271 272| 参数名 | 类型 | 必填 | 说明 | 273| ------ | ------ | ---- | -------------------------------------------- | 274| item | T | 是 | arr中每一个数据项。T为开发者传入的数据类型。 | 275| index | number | 是 | 当前数据项对应的索引。 |