1. 核心作用

• 只渲染可视区域 + 前后缓存的列表项
• 滑出屏幕的组件会被销毁回收，降低内存
• 适合长列表、海量数据场景

2. 支持容器（只有这些才真懒加载）

• List / ListItemGroup
• Grid
• Swiper
• WaterFlow
• 其他容器用 LazyForEach 依然全量加载。

3. 必背使用限制

• 必须放在上述懒加载容器内
• 一个容器里只能有一个 LazyForEach
• 每个 item 必须只有一个根组件
• key 必须唯一且稳定，重复 key 必乱
• 数据源必须实现 IDataSource 接口
• 不能直接赋值 dataSource，必须用 notify 通知更新
• 子组件必须设置明确宽高，否则懒加载失效

4. 三要素语法

ets

LazyForEach(
  数据源: IDataSource,
  item生成函数: (item, index) => 组件,
  key生成函数: (item, index) => string
)

5. 数据源规则（必须实现）

实现 IDataSource 四个方法：

• totalCount ()：总数
• getData (index)：取第几条
• registerDataChangeListener：注册监听
• unregisterDataChangeListener：注销监听
• 更新用 notify 系列：
• notifyDataAdd (index) 新增
• notifyDataDelete (index) 删除
• notifyDataChange (index) 修改单项
• notifyDataMove (from, to) 移动
• notifyDataReload () 全量刷新
• notifyDatasetChange (操作数组) 批量精准更新

6. key 生成规则

• 唯一：不重复
• 稳定：数据不变 key 不变
• 推荐：item.id 或 item + index
• 禁止：固定字符串、Date.now () 等每次都变的值

7. 数据更新方式

• 增：notifyDataAdd
• 删：notifyDataDelete
• 改：notifyDataChange
• 移：notifyDataMove
• 全更：notifyDataReload
• 批量精准：notifyDatasetChange

8. 高级优化

• @Reusable / @ReusableV2：列表项复用
• @Observed + @ObjectLink：深度监听对象属性，只刷新用到的部分
• @ObservedV2 + @Trace：状态管理 V2 深度观测
• cachedCount：设置前后缓存条数，滑动更丝滑
• List + onMove：实现拖拽排序

9. 常见坑（必看）

1. 删除后删错项 原因：index 缓存未更新 解决：key 用 item+index，删除后 reload
2. 图片闪烁 原因：改内容导致 key 变化，重建整个 item 解决：用 @Observed+@ObjectLink 只刷新文本，key 用固定 index
3. @ObjectLink 不刷新 原因：只监听一级属性，深层嵌套不触发 解决：重新赋值一级对象
4. 懒加载失效 原因：子组件没给高度 / 宽度，容器认为全部可见 解决：给 item 固定 height
5. 滚动到底闪烁 原因：用了 notifyDataReload 解决：改用 notifyDatasetChange 精准添加