1# LazyForEach
2
3> **说明**
4>
5> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
6
7开发者指南见：[LazyForEach开发者指南](../../../quick-start/arkts-rendering-control-lazyforeach.md)
8
9## 接口
10
11LazyForEach(dataSource: IDataSource,itemGenerator: (item: any, index: number) => void,keyGenerator?: (item: any, index: number) => string,)
12
13LazyForEach从提供的数据源中按需迭代数据，并在每次迭代过程中创建相应的组件。当在滚动容器中使用了LazyForEach，框架会根据滚动容器可视区域按需创建组件，当组件滑出可视区域外时，框架会进行组件销毁回收以降低内存占用。
14
15**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
16
17**系统能力：** SystemCapability.ArkUI.ArkUI.Full
18
19**参数：**
20
21| 参数名        | 类型                                                      | 必填 | 说明                                                         |
22| ------------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
23| dataSource    | [IDataSource](#idatasource10)                       | 是   | LazyForEach数据源，需要开发者实现相关接口。                  |
24| itemGenerator | (item:&nbsp;Object, index: number)&nbsp;=&gt;&nbsp;void   | 是   | 子组件生成函数，为数组中的每一个数据项创建一个子组件。<br/>**说明：**<br/>- item是当前数据项，index是数据项索引值。<br/>- itemGenerator的函数体必须使用大括号{...}。<br />- itemGenerator每次迭代只能并且必须生成一个子组件。<br />- itemGenerator中可以使用if语句，但是必须保证if语句每个分支都会创建一个相同类型的子组件。<br />- itemGenerator中不允许使用ForEach和LazyForEach语句。 |
25| keyGenerator  | (item:&nbsp;Object, index: number)&nbsp;=&gt;&nbsp;string | 否   | 键值生成函数，用于给数据源中的每一个数据项生成唯一且固定的键值。当数据项在数组中的位置更改时，其键值不得更改，当数组中的数据项被新项替换时，被替换项的键值和新项的键值必须不同。键值生成器的功能是可选的，但是，为了使开发框架能够更好地识别数组更改，提高性能，建议提供。如将数组反向时，如果没有提供键值生成器，则LazyForEach中的所有节点都将重建。<br/>**说明：**<br/>- item是当前数据项，index是数据项索引值。<br/>- 数据源中的每一个数据项生成的键值不能重复。 |
26
27## 属性
28
29继承自[DynamicNode](./ts-rendering-control-foreach.md#dynamicnode12)。
30
31## IDataSource<sup>10+</sup>
32
33**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
34
35**系统能力：** SystemCapability.ArkUI.ArkUI.Full
36
37### totalCount
38
39totalCount(): number
40
41获得数据总数。
42
43**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
44
45**系统能力：** SystemCapability.ArkUI.ArkUI.Full
46
47### getData
48
49getData(index:&nbsp;number): Object
50
51获取索引值index对应的数据。
52
53**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
54
55**系统能力：** SystemCapability.ArkUI.ArkUI.Full
56
57**参数：**
58
59| 参数名 | 类型   | 必填 | 说明                 |
60| ------ | ------ | ---- | -------------------- |
61| index  | number | 是   | 获取数据对应的索引值 |
62
63### registerDataChangeListener
64
65registerDataChangeListener(listener: DataChangeListener): void
66
67注册数据改变的监听器。
68
69**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
70
71**系统能力：** SystemCapability.ArkUI.ArkUI.Full
72
73**参数：**
74
75| 参数名   | 类型                                        | 必填 | 说明           |
76| -------- | ------------------------------------------- | ---- | -------------- |
77| listener | [DataChangeListener](#datachangelistener10) | 是   | 数据变化监听器 |
78
79### unregisterDataChangeListener
80
81unregisterDataChangeListener(listener: DataChangeListener): void
82
83注销数据改变的监听器。
84
85**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
86
87**系统能力：** SystemCapability.ArkUI.ArkUI.Full
88
89**参数：**
90
91| 参数名   | 类型                                        | 必填 | 说明           |
92| -------- | ------------------------------------------- | ---- | -------------- |
93| listener | [DataChangeListener](#datachangelistener10) | 是   | 数据变化监听器 |
94
95## DataChangeListener<sup>10+</sup>
96
97数据变化监听器。
98
99**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
100
101**系统能力：** SystemCapability.ArkUI.ArkUI.Full
102
103### onDataReloaded
104
105onDataReloaded(): void
106
107通知组件重新加载所有数据。键值没有变化的数据项会使用原先的子组件，键值发生变化的会重建子组件。重新加载数据完成后调用。
108
109**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
110
111**系统能力：** SystemCapability.ArkUI.ArkUI.Full
112
113### onDataAdded<sup>(deprecated)</sup>
114
115onDataAdded(index: number): void
116
117通知组件index的位置有数据添加。添加数据完成后调用。
118
119> 从API 8开始，建议使用[onDataAdd](#ondataadd8)。
120
121**系统能力：** SystemCapability.ArkUI.ArkUI.Full
122
123**参数：**
124
125| 参数名 | 类型   | 必填 | 说明                 |
126| ------ | ------ | ---- | -------------------- |
127| index  | number | 是   | 数据添加位置的索引值 |
128
129### onDataMoved<sup>(deprecated)</sup>
130
131onDataMoved(from: number, to: number): void
132
133通知组件数据有移动。将from和to位置的数据进行交换。
134
135> 从API 8开始，建议使用[onDataMove](#ondatamove8)。
136>
137> **说明：** 数据移动前后键值要保持不变，如果键值有变化，应使用删除数据和新增数据接口。数据移动起始位置与数据移动目标位置交换完成后调用。
138
139**系统能力：** SystemCapability.ArkUI.ArkUI.Full
140
141**参数：**
142
143| 参数名 | 类型   | 必填 | 说明             |
144| ------ | ------ | ---- | ---------------- |
145| from   | number | 是   | 数据移动起始位置 |
146| to     | number | 是   | 数据移动目标位置 |
147
148### onDataDeleted<sup>(deprecated)</sup>
149
150onDataDeleted(index: number): void
151
152通知组件删除index位置的数据并刷新LazyForEach的展示内容。删除数据完成后调用。
153
154> 从API 8开始，建议使用[onDataDelete](#ondatadelete8)。
155
156**系统能力：** SystemCapability.ArkUI.ArkUI.Full
157
158**参数：**
159
160| 参数名 | 类型   | 必填 | 说明                 |
161| ------ | ------ | ---- | -------------------- |
162| index  | number | 是   | 数据删除位置的索引值 |
163
164### onDataChanged<sup>(deprecated)</sup>
165
166onDataChanged(index: number): void
167
168通知组件index的位置有数据有变化。改变数据完成后调用。
169
170> 从API 8开始，建议使用[onDataChange](#ondatachange8)。
171
172**系统能力：** SystemCapability.ArkUI.ArkUI.Full
173
174**参数：**
175
176| 参数名 | 类型   | 必填 | 说明           |
177| ------ | ------ | ---- | -------------- |
178| index  | number | 是   | 数据变化监听器 |
179
180### onDataAdd<sup>8+</sup>
181
182onDataAdd(index: number): void
183
184通知组件index的位置有数据添加。添加数据完成后调用
185
186**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
187
188**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
189
190**系统能力：** SystemCapability.ArkUI.ArkUI.Full
191
192**参数：**
193
194| 参数名 | 类型   | 必填 | 说明           |
195| ------ | ------ | ---- | -------------- |
196| index  | number | 是   | 数据添加位置的索引值 |
197
198### onDataMove<sup>8+</sup>
199
200onDataMove(from: number, to: number): void
201
202通知组件数据有移动。将from和to位置的数据进行交换。数据移动起始位置与数据移动目标位置交换完成后调用。
203
204> **说明：** 数据移动前后键值要保持不变，如果键值有变化，应使用删除数据和新增数据接口。
205
206**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
207
208**系统能力：** SystemCapability.ArkUI.ArkUI.Full
209
210**参数：**
211
212| 参数名 | 类型   | 必填 | 说明             |
213| ------ | ------ | ---- | ---------------- |
214| from   | number | 是   | 数据移动起始位置 |
215| to     | number | 是   | 数据移动目标位置 |
216
217### onDataDelete<sup>8+</sup>
218
219onDataDelete(index: number): void
220
221通知组件删除index位置的数据并刷新LazyForEach的展示内容。删除数据完成后调用。
222
223> **说明：** 需要保证dataSource中的对应数据已经在调用onDataDelete前删除，否则页面渲染将出现未定义的行为。
224
225**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
226
227**系统能力：** SystemCapability.ArkUI.ArkUI.Full
228
229**参数：**
230
231| 参数名 | 类型   | 必填 | 说明                 |
232| ------ | ------ | ---- | -------------------- |
233| index  | number | 是   | 数据删除位置的索引值 |
234
235### onDataChange<sup>8+</sup>
236
237onDataChange(index: number): void
238
239通知组件index的位置有数据有变化。改变数据完成后调用。
240
241**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
242
243**系统能力：** SystemCapability.ArkUI.ArkUI.Full
244
245**参数：**
246
247| 参数名 | 类型   | 必填 | 说明                 |
248| ------ | ------ | ---- | -------------------- |
249| index  | number | 是   | 数据变化位置的索引值 |
250
251### onDatasetChange<sup>12+</sup>
252
253onDatasetChange(dataOperations: DataOperation[]): void
254
255进行批量的数据处理后，调用onDatasetChange接口通知组件按照dataOperations刷新组件。
256
257> **说明：** onDatasetChange接口不能与其他DataChangeListener的更新接口混用。如在同一个LazyForEach中，调用过onDataAdd接口后，不能再调用onDatasetChange接口；反之，调用过onDatasetChange接口后，也不能调用onDataAdd等其他更新接口。页面中不同LazyForEach之间互不影响。
258
259**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
260
261**系统能力：** SystemCapability.ArkUI.ArkUI.Full
262
263**参数：**
264
265| 参数名         | 类型                | 必填 | 说明               |
266| -------------- | ------------------- | ---- | ------------------ |
267| dataOperations | [DataOperation](#dataoperation12)[] | 是   | 一次处理数据的操作 |
268
269## DataOperation<sup>12+</sup>
270
271> **说明**
272>
273> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
274
275**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
276
277**系统能力：** SystemCapability.ArkUI.ArkUI.Full
278
279### DataAddOperation
280
281添加数据操作。
282
283**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
284
285**系统能力：** SystemCapability.ArkUI.ArkUI.Full
286
287**参数：**
288
289| 参数名 | 类型                      | 必填 | 说明                 |
290| ------ | ------------------------- | ---- | -------------------- |
291| type   | [DataOperationType](#dataoperationtype枚举说明).ADD     | 是   | 数据添加类型         |
292| index  | number                    | 是   | 插入数据索引值       |
293| count  | number                    | 否   | 插入数量，默认为1    |
294| key    | string \| Array\<string\> | 否   | 为插入的数据分配键值 |
295
296### DataDeleteOperation
297
298删除数据操作。
299
300**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
301
302**系统能力：** SystemCapability.ArkUI.ArkUI.Full
303
304**参数：**
305
306| 参数名 | 类型                      | 必填 | 说明                 |
307| ------ | ------------------------- | ---- | -------------------- |
308| type   | [DataOperationType](#dataoperationtype枚举说明).DELETE     | 是   | 数据删除类型         |
309| index  | number                    | 是   | 起始删除位置索引值       |
310| count  | number                    | 否   | 删除数据数量，默认为1    |
311
312### DataChangeOperation
313
314改变数据操作。
315
316**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
317
318**系统能力：** SystemCapability.ArkUI.ArkUI.Full
319
320**参数：**
321
322| 参数名 | 类型                      | 必填 | 说明                 |
323| ------ | ------------------------- | ---- | -------------------- |
324| type   | [DataOperationType](#dataoperationtype枚举说明).CHANGE     | 是   | 数据改变类型         |
325| index  | number                    | 是   | 改变的数据的索引值       |
326| key  | string                    | 否   | 为改变的数据分配新的键值，默认使用原键值    |
327
328### DataMoveOperation
329
330移动数据操作。
331
332**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
333
334**系统能力：** SystemCapability.ArkUI.ArkUI.Full
335
336**参数：**
337
338| 参数名 | 类型                      | 必填 | 说明                 |
339| ------ | ------------------------- | ---- | -------------------- |
340| type   | [DataOperationType](#dataoperationtype枚举说明).MOVE     | 是   | 数据移动类型 |
341| index  | [MoveIndex](#moveindex)        | 是   | 移动位置   |
342| key | string              | 否   | 为被移动的数据分配新的键值，默认使用原键值 |
343
344#### MoveIndex
345
346**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
347
348**系统能力：** SystemCapability.ArkUI.ArkUI.Full
349
350**参数：**
351
352| 参数名 | 类型                       | 必填 | 说明            |
353| ------ | --------------- | ---- | ------- |
354| from   | number | 是   | 起始移动位置                 |
355| to  | number           | 是   | 目的移动位置           |
356
357### DataExchangeOperation
358
359交换数据操作。
360
361**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
362
363**系统能力：** SystemCapability.ArkUI.ArkUI.Full
364
365**参数：**
366
367| 参数名 | 类型                       | 必填 | 说明                         |
368| ------ | -------------------------- | ---- | ---------------------------- |
369| type   | [DataOperationType](#dataoperationtype枚举说明).EXCHANGE | 是   | 数据交换类型                 |
370| index  | [ExchangeIndex](#exchangeindex)            | 是   | 交换位置                     |
371| key    | [ExchangeKey](#exchangekey)              | 否   | 分配新的键值，默认使用原键值 |
372
373#### ExchangeIndex
374
375**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
376
377**系统能力：** SystemCapability.ArkUI.ArkUI.Full
378
379**参数：**
380
381| 参数名 | 类型                       | 必填 | 说明            |
382| ------ | --------------- | ---- | ------- |
383| start   | number | 是   | 第一个交换位置                 |
384| end  | number           | 是   | 第二个交换位置           |
385
386#### ExchangeKey
387
388**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
389
390**系统能力：** SystemCapability.ArkUI.ArkUI.Full
391
392**参数：**
393
394| 参数名 | 类型                       | 必填 | 说明            |
395| ------ | --------------- | ---- | ------- |
396| start   | string | 是   | 为第一个交换的位置分配新的键值，默认使用原键值        |
397| end  | string   | 是   | 为第二个交换的位置分配新的键值，默认使用原键值           |
398
399### DataReloadOperation
400
401重载所有数据操作。当onDatasetChange含有DataOperationType.RELOAD操作时，其余操作全部失效，框架会自己调用keygenerator进行键值比对。
402
403**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
404
405**系统能力：** SystemCapability.ArkUI.ArkUI.Full
406
407**参数：**
408
409| 参数名 | 类型                     | 必填 | 说明             |
410| ------ | ------------------------ | ---- | ---------------- |
411| type   | [DataOperationType](#dataoperationtype枚举说明).RELOAD | 是   | 数据全部重载类型 |
412
413### DataOperationType枚举说明
414
415枚举类型，数据操作说明。
416
417**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
418
419**系统能力：** SystemCapability.ArkUI.ArkUI.Full
420
421| 名称 | 值                    | 说明                 |
422| ------ | ------------------- | -------------------- |
423| ADD   |   add       | 数据添加   |
424| DELETE  | delete    | 数据删除    |
425| CHANGE  | change     | 数据改变    |
426| MOVE | move | 数据移动 |
427| EXCHANGE | exchange | 数据交换 |
428| RELOAD | reload | 全部数据重载 |