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