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