1# Repeat 2 3> **说明：** 4> 5> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6 7Repeat基于数组类型数据来进行循环渲染，一般与容器组件配合使用。 8本文档仅为API参数说明。开发者指南见：[Repeat开发者指南](../../../quick-start/arkts-new-rendering-control-repeat.md)。 9 10## 接口 11 12Repeat: \<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## 事件 37 38**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 39 40**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 41 42**系统能力：** SystemCapability.ArkUI.ArkUI.Full 43 44### each 45 46each(itemGenerator: (repeatItem: RepeatItem\<T\>) => void): RepeatAttribute\<T\> 47 48组件生成函数。template和templateId匹配不上的数据项走默认生成函数each。 49 50> **说明** 51> 52> `each`属性必须有，否则运行时会报错。 53> `itemGenerator`的参数为`RepeatItem`，该参数将`item`和`index`结合到了一起，请勿将`RepeatItem`参数拆开使用。 54 55**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 56 57**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.ArkUI.ArkUI.Full 60 61**参数：** 62 63| 参数名 | 类型 | 必填 | 说明 | 64| ------ | ---------- | -------- | -------- | 65| repeatItem | [RepeatItem](#repeatitemt)\<T\> | 是 | repeat数据项。 | 66 67**示例：** 68```ts 69// arr是Array<string>类型的数组，为每个数据创建一个Text组件 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 78键值生成函数。 79 80**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 81 82**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.ArkUI.ArkUI.Full 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| ------ | ---------- | -------- | -------- | 90| item | T | 是 | `arr`数组中的数据项。 | 91| index | number | 是 | `arr`数组中的数据项索引。 | 92 93**示例：** 94```ts 95// arr是Array<string>类型的数组，为每个数据创建一个Text组件 96// 并将字符串的值作为其键值 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 106`Repeat`开启虚拟滚动。 107 108**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| ------ | ---------- | -------- | -------- | 116| virtualScrollOptions | [VirtualScrollOptions](#virtualscrolloptions对象说明) | 否 | 虚拟滚动配置项。 | 117 118**示例：** 119```ts 120// arr是Array<string>类型的数组，为每个数据创建一个Text组件 121// 在List容器组件中使用Repeat，并打开virtualScroll 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 133复用模板。 134 135**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 136 137**系统能力：** SystemCapability.ArkUI.ArkUI.Full 138 139**参数：** 140 141| 参数名 | 类型 | 必填 | 说明 | 142| ------ | ---------- | -------- | -------- | 143| type | string | 是 | 当前模板类型。 | 144| itemBuilder | [RepeatItemBuilder](#repeatitembuildert)\<T\> | 是 | 组件生成函数。 | 145| templateOptions | [TemplateOptions](#templateoptions对象说明) | 否 | 当前模板配置项。 | 146 147**示例：** 148```ts 149// arr是Array<string>类型的数组 150// 在List容器组件中使用Repeat，并打开virtualScroll 151// 创建模板temp，该模板为数据创建Text组件 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 164为当前数据项分配templateId。 165 166**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 167 168**系统能力：** SystemCapability.ArkUI.ArkUI.Full 169 170**参数：** 171 172| 参数名 | 类型 | 必填 | 说明 | 173| ------ | ---------- | -------- | -------- | 174| typedFunc | [TemplateTypedFunc](#templatetypedfunct)\<T\> | 是 | 生成当前数据项对应的templateId。 | 175 176**示例：** 177```ts 178// arr是Array<string>类型的数组 179// 在List容器组件中使用Repeat，并打开virtualScroll 180// 创建模板temp，该模板为数据创建Text组件 181// 所有数据项都使用temp模板 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**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 194 195**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 196 197**系统能力：** SystemCapability.ArkUI.ArkUI.Full 198 199| 名称 | 类型 | 必填 | 说明 | 200| ------ | ------ | ---- | -------------------------------------------- | 201| item | T | 是 | arr中每一个数据项。T为开发者传入的数据类型。 | 202| index | number | 是 | 当前数据项对应的索引。 | 203 204## VirtualScrollOptions对象说明 205 206**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 207 208**系统能力：** SystemCapability.ArkUI.ArkUI.Full 209 210| 名称 | 类型 | 必填 | 说明 | 211| ---------- | ------ | ---- | ------------------------------------------------------------ | 212| totalCount | number | 否 | 加载的数据项总数，可以大于/小于数据源长度 | 213 214**示例：** 215```ts 216// arr是Array<string>类型的数组，在List容器组件中使用Repeat，并打开virtualScroll 217// 将加载的数据项总数设为数据源的长度 218List() { 219 Repeat<string>(this.arr) 220 .each((obj: RepeatItem<string>) => { ListItem() { Text(obj.item) }}) 221 .virtualScroll( { totalCount: this.arr.length } ) 222} 223``` 224 225## RepeatItemBuilder\<T\> 226 227type RepeatItemBuilder\<T\> = (repeatItem: RepeatItem\<T\>) => void 228 229**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 230 231**系统能力：** SystemCapability.ArkUI.ArkUI.Full 232 233**参数：** 234 235| 参数名 | 类型 | 必填 | 说明 | 236| ---------- | ------------- | --------------------------------------- | --------------------------------------- | 237| repeatItem | [RepeatItem](#repeatitemt)\<T\> | 是 | 将item和index结合到一起的一个状态变量。 | 238 239## TemplateOptions对象说明 240 241**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 242 243**系统能力：** SystemCapability.ArkUI.ArkUI.Full 244 245| 名称 | 类型 | 必填 | 说明 | 246| ----------- | ------ | ---- | ------------------------------------------------------------ | 247| cachedCount | number | 否 | 当前模板在Repeat的缓存池中可缓存子节点的最大数量，仅在开启virtualScroll后生效。 | 248 249**示例：** 250```ts 251// arr是Array<string>类型的数组，在List容器组件中使用Repeat，并打开virtualScroll 252// 创建模板temp，该模板为数据创建Text组件，所有数据项都使用temp模板 253// 将temp模板的最大缓存节点数量设为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**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 268 269**系统能力：** SystemCapability.ArkUI.ArkUI.Full 270 271**参数：** 272 273| 参数名 | 类型 | 必填 | 说明 | 274| ------ | ------ | ---- | -------------------------------------------- | 275| item | T | 是 | arr中每一个数据项。T为开发者传入的数据类型。 | 276| index | number | 是 | 当前数据项对应的索引。 |