1# LazyForEach 2 3> **NOTE** 4> 5> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 6 7For details about the development, see [LazyForEach: Lazy Data Loading](../../../quick-start/arkts-rendering-control-lazyforeach.md). 8 9## APIs 10 11LazyForEach(dataSource: IDataSource,itemGenerator: (item: any, index: number) => void,keyGenerator?: (item: any, index: number) => string,) 12 13**LazyForEach** iterates over provided data sources and creates corresponding components during each iteration. When **LazyForEach** is used in a scrolling container, the framework creates components as required within the visible area of the scrolling container. When a component is out of the visible area, the framework destroys and reclaims the component to reduce memory usage. 14 15**Atomic service API**: This API can be used in atomic services since API version 11. 16 17**System capability**: SystemCapability.ArkUI.ArkUI.Full 18 19**Parameters** 20 21| Name | Type | Mandatory| Description | 22| ------------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 23| dataSource | [IDataSource](#idatasource10) | Yes | **LazyForEach** data source. You need to implement related APIs. | 24| itemGenerator | (item: Object, index: number) => void | Yes | Child component generation function, which generates a child component for each data item in the array.<br>**NOTE**<br>- **item** indicates the current data item, and **index** indicates the index of the data item.<br>- The function body of **itemGenerator** must be included in braces {...}.<br>- **itemGenerator** can and must generate only one child component for each iteration.<br>- The **if** statement is allowed in **itemGenerator**, but you must ensure that each branch of the **if** statement creates a child component of the same type.<br>- **ForEach** and **LazyForEach** statements are not allowed in **itemGenerator**.| 25| keyGenerator | (item: Object, index: number) => string | No | ID generation function, which generates a unique and fixed ID for each data item in the data source. This ID must remain unchanged for the data item even when the item is relocated in the array. When the item is replaced by a new item, the ID of the new item must be different from that of the replaced item. This ID generation function is optional. However, for performance reasons, it is strongly recommended that the ID generation function be provided, so that the framework can better identify array changes. For example, if no ID generation function is provided, a reverse of an array will result in rebuilding of all nodes in **LazyForEach**.<br>**NOTE**<br>- **item** indicates the current data item, and **index** indicates the index of the data item.<br>- The ID generated for each data item in the data source must be unique.| 26 27## Name 28 29Inherited from [DynamicNode](./ts-rendering-control-foreach.md#dynamicnode12). 30 31## IDataSource<sup>10+</sup> 32 33**Atomic service API**: This API can be used in atomic services since API version 11. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37### totalCount 38 39totalCount(): number 40 41Obtains the total number of data items. 42 43**Atomic service API**: This API can be used in atomic services since API version 11. 44 45**System capability**: SystemCapability.ArkUI.ArkUI.Full 46 47### getData 48 49getData(index: number): Object 50 51Obtains the data item that matches the specified index. 52 53**Atomic service API**: This API can be used in atomic services since API version 11. 54 55**System capability**: SystemCapability.ArkUI.ArkUI.Full 56 57**Parameters** 58 59| Name| Type | Mandatory| Description | 60| ------ | ------ | ---- | -------------------- | 61| index | number | Yes | Index of the data record to obtain.| 62 63### registerDataChangeListener 64 65registerDataChangeListener(listener: DataChangeListener): void 66 67Registers a listener for data changes. 68 69**Atomic service API**: This API can be used in atomic services since API version 11. 70 71**System capability**: SystemCapability.ArkUI.ArkUI.Full 72 73**Parameters** 74 75| Name | Type | Mandatory| Description | 76| -------- | ------------------------------------------- | ---- | -------------- | 77| listener | [DataChangeListener](#datachangelistener10) | Yes | Listener for data changes.| 78 79### unregisterDataChangeListener 80 81unregisterDataChangeListener(listener: DataChangeListener): void 82 83Unregisters the listener for data changes. 84 85**Atomic service API**: This API can be used in atomic services since API version 11. 86 87**System capability**: SystemCapability.ArkUI.ArkUI.Full 88 89**Parameters** 90 91| Name | Type | Mandatory| Description | 92| -------- | ------------------------------------------- | ---- | -------------- | 93| listener | [DataChangeListener](#datachangelistener10) | Yes | Listener for data changes.| 94 95## DataChangeListener<sup>10+</sup> 96 97Listener for data changes. 98 99> **NOTE** 100> 101> In APIs of **DataChangeListener** other than **onDatasetChange**, if the value of **index** is negative, the value is treated as **0** by default. In **onDatasetChange**, if the specified index in a **DataOperation** is outside the data source index range, the corresponding **DataOperation** does not take effect. (In **DataAddOperation**, the value of **index** can equal the data source length.) 102 103**Atomic service API**: This API can be used in atomic services since API version 11. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107### onDataReloaded 108 109onDataReloaded(): void 110 111Invoked when all data is reloaded. For data items whose key remains unchanged, the original child component is used. For data items whose key changes, a new child component is created. 112 113**Atomic service API**: This API can be used in atomic services since API version 11. 114 115**System capability**: SystemCapability.ArkUI.ArkUI.Full 116 117### onDataAdded<sup>(deprecated)</sup> 118 119onDataAdded(index: number): void 120 121Invoked when data is added to the position indicated by the specified index. 122 123> This API is deprecated since API version 8. You are advised to use [onDataAdd](#ondataadd8) instead. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Parameters** 128 129| Name| Type | Mandatory| Description | 130| ------ | ------ | ---- | -------------------- | 131| index | number | Yes | Index of the position where data is added.| 132 133### onDataMoved<sup>(deprecated)</sup> 134 135onDataMoved(from: number, to: number): void 136 137Invoked when data is moved, that is, when data is swapped between the **from** and **to** positions. 138 139> This API is deprecated since API version 8. You are advised to use [onDataMove](#ondatamove8) instead. 140 141> **NOTE** 142> 143> The ID must remain unchanged before and after data movement. If the ID changes, APIs for deleting and adding data must be called. 144 145**System capability**: SystemCapability.ArkUI.ArkUI.Full 146 147**Parameters** 148 149| Name| Type | Mandatory| Description | 150| ------ | ------ | ---- | ---------------- | 151| from | number | Yes | Original position of data.| 152| to | number | Yes | Target position of data.| 153 154### onDataDeleted<sup>(deprecated)</sup> 155 156onDataDeleted(index: number): void 157 158Invoked when data is deleted from the position indicated by the specified index. LazyForEach will update the displayed content accordingly. 159 160> This API is deprecated since API version 8. You are advised to use [onDataDelete](#ondatadelete8) instead. 161 162**System capability**: SystemCapability.ArkUI.ArkUI.Full 163 164**Parameters** 165 166| Name| Type | Mandatory| Description | 167| ------ | ------ | ---- | -------------------- | 168| index | number | Yes | Index of the position where data is deleted.| 169 170### onDataChanged<sup>(deprecated)</sup> 171 172onDataChanged(index: number): void 173 174Invoked when data in the position indicated by the specified index is changed. 175 176> This API is deprecated since API version 8. You are advised to use [onDataChange](#ondatachange8) instead. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Parameters** 181 182| Name| Type | Mandatory| Description | 183| ------ | ------ | ---- | -------------- | 184| index | number | Yes | Listener for data changes.| 185 186### onDataAdd<sup>8+</sup> 187 188onDataAdd(index: number): void 189 190Invoked when data is added to the position indicated by the specified index. 191 192**Widget capability**: This API can be used in ArkTS widgets since API version 10. 193 194**Atomic service API**: This API can be used in atomic services since API version 11. 195 196**System capability**: SystemCapability.ArkUI.ArkUI.Full 197 198**Parameters** 199 200| Name| Type | Mandatory| Description | 201| ------ | ------ | ---- | -------------- | 202| index | number | Yes | Index of the position where data is added.| 203 204### onDataMove<sup>8+</sup> 205 206onDataMove(from: number, to: number): void 207 208Invoked when data is moved, that is, when data is swapped between the **from** and **to** positions. 209 210> **NOTE** 211> 212> The ID must remain unchanged before and after data movement. If the ID changes, APIs for deleting and adding data must be called. 213 214**Atomic service API**: This API can be used in atomic services since API version 11. 215 216**System capability**: SystemCapability.ArkUI.ArkUI.Full 217 218**Parameters** 219 220| Name| Type | Mandatory| Description | 221| ------ | ------ | ---- | ---------------- | 222| from | number | Yes | Original position of data.| 223| to | number | Yes | Target position of data.| 224 225### onDataDelete<sup>8+</sup> 226 227onDataDelete(index: number): void 228 229Invoked when data is deleted from the position indicated by the specified index. LazyForEach will update the displayed content accordingly. 230 231> **NOTE** 232> 233> Before **onDataDelete** is called, ensure that the corresponding data in **dataSource** has been deleted. Otherwise, undefined behavior will occur during page rendering. 234 235**Atomic service API**: This API can be used in atomic services since API version 11. 236 237**System capability**: SystemCapability.ArkUI.ArkUI.Full 238 239**Parameters** 240 241| Name| Type | Mandatory| Description | 242| ------ | ------ | ---- | -------------------- | 243| index | number | Yes | Index of the position where data is deleted.| 244 245### onDataChange<sup>8+</sup> 246 247onDataChange(index: number): void 248 249Invoked when data in the position indicated by the specified index is changed. 250 251**Atomic service API**: This API can be used in atomic services since API version 11. 252 253**System capability**: SystemCapability.ArkUI.ArkUI.Full 254 255**Parameters** 256 257| Name| Type | Mandatory| Description | 258| ------ | ------ | ---- | -------------------- | 259| index | number | Yes | Index of the position where data is changed.| 260 261### onDatasetChange<sup>12+</sup> 262 263onDatasetChange(dataOperations: DataOperation[]): void 264 265Invoked when data is processed in batches to notify the component of refreshing. 266 267> **NOTE** 268> 269> This API cannot be used together with other data operation APIs of **DataChangeListener**. For example, in the same **LazyForEach**, if you have called **onDataAdd**, do not call **onDatasetChange**; if you have called **onDatasetChange**, do not call **onDataAdd** or other data operation APIs. Different **LazyForEach** instances on the page do not affect each other. 270 271**Atomic service API**: This API can be used in atomic services since API version 12. 272 273**System capability**: SystemCapability.ArkUI.ArkUI.Full 274 275**Parameters** 276 277| Name | Type | Mandatory| Description | 278| -------------- | ------------------- | ---- | ------------------ | 279| dataOperations | [DataOperation](#dataoperation12)[] | Yes | Array of data operations performed.| 280 281## DataOperation<sup>12+</sup> 282 283> **NOTE** 284> 285> 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. 286 287**Atomic service API**: This API can be used in atomic services since API version 12. 288 289**System capability**: SystemCapability.ArkUI.ArkUI.Full 290 291### DataAddOperation 292 293Represents an operation for adding data. 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**Parameters** 300 301| Name| Type | Mandatory| Description | 302| ------ | ------------------------- | ---- | -------------------- | 303| type | [DataOperationType](#dataoperationtype).ADD | Yes | Type of data addition. | 304| index | number | Yes | Index at which to insert the data record. | 305| count | number | No | Number of data records to insert.<br>Default value: **1**. | 306| key | string \| Array\<string\> | No | Keys to assign to the inserted data records.| 307 308### DataDeleteOperation 309 310Represents an operation for deleting data. 311 312**Atomic service API**: This API can be used in atomic services since API version 12. 313 314**System capability**: SystemCapability.ArkUI.ArkUI.Full 315 316**Parameters** 317 318| Name| Type | Mandatory| Description | 319| ------ | ------------------------- | ---- | -------------------- | 320| type | [DataOperationType](#dataoperationtype).DELETE | Yes | Type of data deletion. | 321| index | number | Yes | Index at which to start deleting data. | 322| count | number | No | Number of data records to delete.<br>Default value: **1**. | 323 324### DataChangeOperation 325 326Represents an operation for changing data. 327 328**Atomic service API**: This API can be used in atomic services since API version 12. 329 330**System capability**: SystemCapability.ArkUI.ArkUI.Full 331 332**Parameters** 333 334| Name| Type | Mandatory| Description | 335| ------ | ------------------------- | ---- | -------------------- | 336| type | [DataOperationType](#dataoperationtype).CHANGE | Yes | Type of data change. | 337| index | number | Yes | Index of the data to be changed. | 338| key | string | No | New key to assign to the changed data. The original key is used by default. | 339 340### DataMoveOperation 341 342Represents an operation for moving data. 343 344**Atomic service API**: This API can be used in atomic services since API version 12. 345 346**System capability**: SystemCapability.ArkUI.ArkUI.Full 347 348**Parameters** 349 350| Name| Type | Mandatory| Description | 351| ------ | ------------------------- | ---- | -------------------- | 352| type | [DataOperationType](#dataoperationtype).MOVE | Yes | Type of data movement.| 353| index | [MoveIndex](#moveindex) | Yes | Positions for the movement. | 354| key | string | No | New key to assign to the moved data. The original key is used by default.| 355 356#### MoveIndex 357 358**Atomic service API**: This API can be used in atomic services since API version 12. 359 360**System capability**: SystemCapability.ArkUI.ArkUI.Full 361 362**Parameters** 363 364| Name| Type | Mandatory| Description | 365| ------ | --------------- | ---- | ------- | 366| from | number | Yes | Start position for the movement. | 367| to | number | Yes | End position for the movement. | 368 369### DataExchangeOperation 370 371Represents an operation for exchanging data. 372 373**Atomic service API**: This API can be used in atomic services since API version 12. 374 375**System capability**: SystemCapability.ArkUI.ArkUI.Full 376 377**Parameters** 378 379| Name| Type | Mandatory| Description | 380| ------ | -------------------------- | ---- | ---------------------------- | 381| type | [DataOperationType](#dataoperationtype).EXCHANGE | Yes | Type of data exchange. | 382| index | [ExchangeIndex](#exchangeindex) | Yes | Positions for the exchange. | 383| key | [ExchangeKey](#exchangekey) | No | New keys to assign to the exchanged data. The original keys are used by default.| 384 385#### ExchangeIndex 386 387**Atomic service API**: This API can be used in atomic services since API version 12. 388 389**System capability**: SystemCapability.ArkUI.ArkUI.Full 390 391**Parameters** 392 393| Name| Type | Mandatory| Description | 394| ------ | --------------- | ---- | ------- | 395| start | number | Yes | First position for the exchange. | 396| end | number | Yes | Second position for the exchange. | 397 398#### ExchangeKey 399 400**Atomic service API**: This API can be used in atomic services since API version 12. 401 402**System capability**: SystemCapability.ArkUI.ArkUI.Full 403 404**Parameters** 405 406| Name| Type | Mandatory| Description | 407| ------ | --------------- | ---- | ------- | 408| start | string | Yes | New key to assign to the first position in the exchange. The original key is used by default. | 409| end | string | Yes | New key to assign to the second position in the exchange. The original key is used by default. | 410 411### DataReloadOperation 412 413Represents an operation for reloading data. If the **onDatasetChange** event contains a **DataOperationType.RELOAD** operation, all other operations in the event are ineffective. In such cases, the framework will call **keygenerator** to perform a comparison of keys with their corresponding values. 414 415**Atomic service API**: This API can be used in atomic services since API version 12. 416 417**System capability**: SystemCapability.ArkUI.ArkUI.Full 418 419**Parameters** 420 421| Name| Type | Mandatory| Description | 422| ------ | ------------------------ | ---- | ---------------- | 423| type | [DataOperationType](#dataoperationtype).RELOAD | Yes | Type of data reloading.| 424 425### DataOperationType 426 427Enumerates the data operation types. 428 429**Atomic service API**: This API can be used in atomic services since API version 12. 430 431**System capability**: SystemCapability.ArkUI.ArkUI.Full 432 433| Name| Value | Description | 434| ------ | ------------------- | -------------------- | 435| ADD | add | Data addition. | 436| DELETE | delete | Data deletion. | 437| CHANGE | change | Data change. | 438| MOVE | move | Data movement.| 439| EXCHANGE | exchange | Data exchange.| 440| RELOAD | reload | Data reloading.| 441