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**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. 10 11**Widget capability**: This API can be used in ArkTS widgets since API version 10. 12 13**Atomic service API**: This API can be used in atomic services since API version 11. 14 15**System capability**: SystemCapability.ArkUI.ArkUI.Full 16 17**Parameters** 18 19| Name | Type | Mandatory| Description | 20| ------------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 21| dataSource | [IDataSource](#idatasource10) | Yes | **LazyForEach** data source. You need to implement related APIs. | 22| 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**.| 23| 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.| 24 25## onMove<sup>12+</sup> 26 27onMove(handler: Optional<(from: index, to: index) => void>): T 28 29Invoked when data is moved after sorting with dragging. This API takes effect only when it is used in a list and a list item is generated in each iteration of **LazyForEach**. 30 31**Widget capability**: This API can be used in ArkTS widgets since API version 12. 32 33**Atomic service API**: This API can be used in atomic services since API version 12. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37**Parameters** 38 39| Name| Type | Mandatory| Description | 40| ------ | --------- | ---- | ---------- | 41| from | number | Yes | Start index of the data before movement.| 42| to | number | Yes | Target index of the data after movement.| 43 44## IDataSource<sup>10+</sup> 45 46**Widget capability**: This API can be used in ArkTS widgets since API version 10. 47 48**Atomic service API**: This API can be used in atomic services since API version 11. 49 50**System capability**: SystemCapability.ArkUI.ArkUI.Full 51 52### totalCount 53 54totalCount(): number 55 56Obtains the total number of data items. 57 58**Widget capability**: This API can be used in ArkTS widgets since API version 10. 59 60**Atomic service API**: This API can be used in atomic services since API version 11. 61 62**System capability**: SystemCapability.ArkUI.ArkUI.Full 63 64### getData 65 66getData(index: number): Object 67 68Obtains the data item that matches the specified index. 69 70**Widget capability**: This API can be used in ArkTS widgets since API version 10. 71 72**Atomic service API**: This API can be used in atomic services since API version 11. 73 74**System capability**: SystemCapability.ArkUI.ArkUI.Full 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | ------ | ---- | -------------------- | 80| index | number | Yes | Index of the data record to obtain.| 81 82### registerDataChangeListener 83 84registerDataChangeListener(listener: DataChangeListener): void 85 86Registers a listener for data changes. 87 88**Widget capability**: This API can be used in ArkTS widgets since API version 10. 89 90**Atomic service API**: This API can be used in atomic services since API version 11. 91 92**System capability**: SystemCapability.ArkUI.ArkUI.Full 93 94**Parameters** 95 96| Name | Type | Mandatory| Description | 97| -------- | ------------------------------------------- | ---- | -------------- | 98| listener | [DataChangeListener](#datachangelistener10) | Yes | Listener for data changes.| 99 100### unregisterDataChangeListener 101 102unregisterDataChangeListener(listener: DataChangeListener): void 103 104Unregisters the listener for data changes. 105 106**Widget capability**: This API can be used in ArkTS widgets since API version 10. 107 108**Atomic service API**: This API can be used in atomic services since API version 11. 109 110**System capability**: SystemCapability.ArkUI.ArkUI.Full 111 112**Parameters** 113 114| Name | Type | Mandatory| Description | 115| -------- | ------------------------------------------- | ---- | -------------- | 116| listener | [DataChangeListener](#datachangelistener10) | Yes | Listener for data changes.| 117 118## DataChangeListener<sup>10+</sup> 119 120Implements the listener for data changes. 121 122**Widget capability**: This API can be used in ArkTS widgets since API version 10. 123 124**Atomic service API**: This API can be used in atomic services since API version 11. 125 126**System capability**: SystemCapability.ArkUI.ArkUI.Full 127 128### onDataReloaded 129 130onDataReloaded(): void 131 132Invoked 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. 133 134**Widget capability**: This API can be used in ArkTS widgets since API version 10. 135 136**Atomic service API**: This API can be used in atomic services since API version 11. 137 138**System capability**: SystemCapability.ArkUI.ArkUI.Full 139 140### onDataAdded<sup>(deprecated)</sup> 141 142onDataAdded(index: number): void 143 144Invoked when data is added to the position indicated by the specified index. 145 146> This API is deprecated since API version 8. You are advised to use [onDataAdd](#ondataadd8) instead. 147 148**Parameters** 149 150| Name| Type | Mandatory| Description | 151| ------ | ------ | ---- | -------------------- | 152| index | number | Yes | Index of the position where data is added.| 153 154### onDataMoved<sup>(deprecated)</sup> 155 156onDataMoved(from: number, to: number): void 157 158Invoked when data is moved. Data is swapped between the **from** and **to** positions. 159 160> This API is deprecated since API version 8. You are advised to use [onDataMove](#ondatamove8) instead. 161> 162> The ID must remain unchanged before and after data movement. If the ID changes, APIs for deleting and adding data must be called. 163 164**Parameters** 165 166| Name| Type | Mandatory| Description | 167| ------ | ------ | ---- | ---------------- | 168| from | number | Yes | Original position of data.| 169| to | number | Yes | Target position of data.| 170 171### onDataDeleted<sup>(deprecated)</sup> 172 173onDataDeleted(index: number): void 174 175Invoked when data is deleted from the position indicated by the specified index. LazyForEach will update the displayed content accordingly. 176 177> This API is deprecated since API version 8. You are advised to use [onDataDelete](#ondatadelete8) instead. 178 179**Parameters** 180 181| Name| Type | Mandatory| Description | 182| ------ | ------ | ---- | -------------------- | 183| index | number | Yes | Index of the position where data is deleted.| 184 185### onDataChanged<sup>(deprecated)</sup> 186 187onDataChanged(index: number): void 188 189Invoked when data in the position indicated by the specified index is changed. 190 191> This API is deprecated since API version 8. You are advised to use [onDataChange](#ondatachange8) instead. 192 193**Parameters** 194 195| Name| Type | Mandatory| Description | 196| ------ | ------ | ---- | -------------- | 197| index | number | Yes | Listener for data changes.| 198 199### onDataAdd<sup>8+</sup> 200 201onDataAdd(index: number): void 202 203Invoked when data is added to the position indicated by the specified index. 204 205| Name| Type | Mandatory| Description | 206| ------ | ------ | ---- | -------------- | 207| index | number | Yes | Index of the position where data is added.| 208 209**Widget capability**: This API can be used in ArkTS widgets since API version 10. 210 211**Atomic service API**: This API can be used in atomic services since API version 11. 212 213**System capability**: SystemCapability.ArkUI.ArkUI.Full 214 215**Parameters** 216 217### onDataMove<sup>8+</sup> 218 219onDataMove(from: number, to: number): void 220 221Invoked when data is moved, that is, when data is swapped between the **from** and **to** positions. 222 223> **NOTE** 224> 225> The ID must remain unchanged before and after data movement. If the ID changes, APIs for deleting and adding data must be called. 226 227**Parameters** 228 229| Name| Type | Mandatory| Description | 230| ------ | ------ | ---- | ---------------- | 231| from | number | Yes | Original position of data.| 232| to | number | Yes | Target position of data.| 233 234### onDataDelete<sup>8+</sup> 235 236onDataDelete(index: number): void 237 238Invoked when data is deleted from the position indicated by the specified index. LazyForEach will update the displayed content accordingly. 239 240> **NOTE** 241> 242> Before **onDataDelete** is called, ensure that the corresponding data in **dataSource** has been deleted. Otherwise, undefined behavior will occur during page rendering. 243 244**Widget capability**: This API can be used in ArkTS widgets since API version 10. 245 246**Atomic service API**: This API can be used in atomic services since API version 11. 247 248**System capability**: SystemCapability.ArkUI.ArkUI.Full 249 250**Parameters** 251 252| Name| Type | Mandatory| Description | 253| ------ | ------ | ---- | -------------------- | 254| index | number | Yes | Index of the position where data is deleted.| 255 256### onDataChange<sup>8+</sup> 257 258onDataChange(index: number): void 259 260Invoked when data in the position indicated by the specified index is changed. 261 262**Widget capability**: This API can be used in ArkTS widgets since API version 10. 263 264**Atomic service API**: This API can be used in atomic services since API version 11. 265 266**System capability**: SystemCapability.ArkUI.ArkUI.Full 267 268**Parameters** 269 270| Name| Type | Mandatory| Description | 271| ------ | ------ | ---- | -------------------- | 272| index | number | Yes | Index of the position where data is changed.| 273 274### onDatasetChange<sup>12+</sup> 275 276onDatasetChange(dataOperations: DataOperation[]): void 277 278Invoked when data is changed in batches. It cannot be used together with the aforementioned APIs. 279 280**Widget capability**: This API can be used in ArkTS widgets since API version 12. 281 282**Atomic service API**: This API can be used in atomic services since API version 12. 283 284**System capability**: SystemCapability.ArkUI.ArkUI.Full 285 286**Parameters** 287 288| Name | Type | Mandatory| Description | 289| -------------- | ------------------- | ---- | ------------------ | 290| dataOperations | [DataOperation](#dataoperation12)[] | Yes | Data processing operation.| 291 292## DataOperation<sup>12+</sup> 293 294> **NOTE** 295> 296> 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. 297 298### DataAddOperation 299 300Represents an operation for adding data. 301 302**Widget capability**: This API can be used in ArkTS widgets since API version 12. 303 304**Atomic service API**: This API can be used in atomic services since API version 12. 305 306**System capability**: SystemCapability.ArkUI.ArkUI.Full 307 308**Parameters** 309 310| Name| Type | Mandatory| Description | 311| ------ | ------------------------- | ---- | -------------------- | 312| type | [DataOperationType](#dataoperationtype).ADD | Yes | Type of data operation, specifically for adding data records. | 313| index | number | Yes | Index at which to insert the data record. | 314| count | number | No | Number of data records to insert.<br>Default value: **1** | 315| key | string \| Array\<string\> | No | Keys to assign to the inserted data records.| 316 317### DataDeleteOperation 318 319Represents an operation for deleting data. 320 321**Widget capability**: This API can be used in ArkTS widgets since API version 12. 322 323**Atomic service API**: This API can be used in atomic services since API version 12. 324 325**System capability**: SystemCapability.ArkUI.ArkUI.Full 326 327**Parameters** 328 329| Name| Type | Mandatory| Description | 330| ------ | ------------------------- | ---- | -------------------- | 331| type | [DataOperationType](#dataoperationtype).DELETE | Yes | Type of data operation, specifically for deleting data records. | 332| index | number | Yes | Index at which to start deleting data records. | 333| count | number | No | Number of data records to delete.<br>Default value: **1** | 334 335### DataChangeOperation 336 337Represents an operation for changing data. 338 339**Widget capability**: This API can be used in ArkTS widgets since API version 12. 340 341**Atomic service API**: This API can be used in atomic services since API version 12. 342 343**System capability**: SystemCapability.ArkUI.ArkUI.Full 344 345**Parameters** 346 347| Name| Type | Mandatory| Description | 348| ------ | ------------------------- | ---- | -------------------- | 349| type | [DataOperationType](#dataoperationtype).CHANGE | Yes | Type of data operation, specifically for changing data records. | 350| index | number | Yes | Index of the data record to change. | 351| key | string | No | New key to assign to the changed data. The original key is used by default. | 352 353### DataMoveOperation 354 355Represents an operation for moving data. 356 357**Widget capability**: This API can be used in ArkTS widgets since API version 12. 358 359**Atomic service API**: This API can be used in atomic services since API version 12. 360 361**System capability**: SystemCapability.ArkUI.ArkUI.Full 362 363**Parameters** 364 365| Name| Type | Mandatory| Description | 366| ------ | ------------------------- | ---- | -------------------- | 367| type | [DataOperationType](#dataoperationtype).MOVE | Yes | Type of data operation, specifically for moving data records.| 368| index | [MoveIndex](#moveindex) | Yes | Position to move the data record to or from. | 369| key | string | No | New key to assign to the moved data. The original key is used by default.| 370 371#### MoveIndex 372 373| Name| Type | Mandatory| Description | 374| ------ | --------------- | ---- | ------- | 375| from | number | Yes | Starting position for the movement. | 376| to | number | Yes | Destination position for the movement. | 377 378### DataExchangeOperation 379 380Represents an operation for exchanging data. 381 382**Widget capability**: This API can be used in ArkTS widgets since API version 12. 383 384**Atomic service API**: This API can be used in atomic services since API version 12. 385 386**System capability**: SystemCapability.ArkUI.ArkUI.Full 387 388**Parameters** 389 390| Name| Type | Mandatory| Description | 391| ------ | -------------------------- | ---- | ---------------------------- | 392| type | [DataOperationType](#dataoperationtype).EXCHANGE | Yes | Type of data operation, specifically for exchanging data records. | 393| index | [ExchangeIndex](#exchangeindex) | Yes | Positions to be exchanged. | 394| key | [ExchangeKey](#exchangekey) | No | New keys to assign to the exchanged positions. The original keys are used by default.| 395 396#### ExchangeIndex 397 398| Name| Type | Mandatory| Description | 399| ------ | --------------- | ---- | ------- | 400| start | number | Yes | First position for the exchange. | 401| end | number | Yes | Second position for the exchange. | 402 403#### ExchangeKey 404 405| Name| Type | Mandatory| Description | 406| ------ | --------------- | ---- | ------- | 407| start | string | Yes | New key to assign to the first position in the exchange. The original key is used by default. | 408| end | string | Yes | New key to assign to the second position in the exchange. The original key is used by default. | 409 410### DataReloadOperation 411 412Represents 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. 413 414**Widget capability**: This API can be used in ArkTS widgets since API version 12. 415 416**Atomic service API**: This API can be used in atomic services since API version 12. 417 418**System capability**: SystemCapability.ArkUI.ArkUI.Full 419 420**Parameters** 421 422| Name| Type | Mandatory| Description | 423| ------ | ------------------------ | ---- | ---------------- | 424| type | [DataOperationType](#dataoperationtype).RELOAD | Yes | Type of data operation, specifically for reloading all data records.| 425 426### DataOperationType 427 428Enumerates the data operation types. 429 430**Widget capability**: This API can be used in ArkTS widgets since API version 12. 431 432**Atomic service API**: This API can be used in atomic services since API version 12. 433 434**System capability**: SystemCapability.ArkUI.ArkUI.Full 435 436**Enum description** 437 438| Name| Value | Description | 439| ------ | ------------------- | -------------------- | 440| ADD | add | Data addition. | 441| DELETE | delete | Data deletion. | 442| CHANGE | change | Data change. | 443| MOVE | move | Data movement.| 444| EXCHANGE | exchange | Data exchange.| 445| RELOAD | reload | Data reloading.| 446