《Web 到 HarmonyOS》-- LazyForEach 落在哪些容器:List / Grid / Swiper / WaterFlow / ListIt

1 阅读7分钟

系列:《Web 到 HarmonyOS》· 列表专题续
适合人群:已理解 ForEach / LazyForEach 差别,准备按场景选型滚动容器


写在前面

LazyForEach 不是「万能 v-for」。它只在支持懒加载的滚动容器里,才会按可视区创建 / 回收子节点;塞进普通 Column / Scroll 套一堆子组件,往往还是一次性全建。

官方明确支持懒加载(可配 cachedCount)的容器:

容器Web 心智子项根节点通常是
List纵向/横向列表ListItem
ListItemGroup分组 section(必须在 List 里)ListItem
GridCSS Grid / 宫格GridItem
Swiper轮播 / 分页滑页单页根组件(常直接内容,不必再套 ListItem)
WaterFlow瀑布流 / PinterestFlowItem

共性铁律(五个容器都适用):

  1. 容器内只放一个 LazyForEach(不要和大量静态子项 / 另一个 LazyForEach / ForEach 硬拼)。
  2. 每次迭代只生成一个根子组件,且类型要符合该容器要求。
  3. 改数据走 DataChangeListener,不要重赋值 dataSource。
  4. key 唯一且稳定;默认 key 带 index,中间插入易错位。
  5. 父容器主轴尺寸、子项尺寸缺失时,懒加载可能失效(算不出可视区要建几个)。
  6. 需要节点复用时,把 @Reusable 打在 item 组件上,不是打在 LazyForEach 关键字上。

下面共用同一套数据源骨架,再按容器换外壳。


一、共用:IDataSource + listener

class BasicDataSource implements IDataSource {
  private list: string[] = []
  private listeners: DataChangeListener[] = []

  totalCount(): number {
    return this.list.length
  }

  getData(index: number): string {
    return this.list[index]
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener)
    }
  }

  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener)
    if (pos >= 0) {
      this.listeners.splice(pos, 1)
    }
  }

  pushData(value: string): void {
    this.list.push(value)
    this.notifyAdd(this.list.length - 1)
  }

  deleteData(index: number): void {
    this.list.splice(index, 1)
    this.notifyDelete(index)
  }

  moveData(from: number, to: number): void {
    const item = this.list.splice(from, 1)[0]
    this.list.splice(to, 0, item)
    this.notifyMove(from, to)
  }

  private notifyAdd(index: number): void {
    this.listeners.forEach((l: DataChangeListener) => l.onDataAdd(index))
  }

  private notifyDelete(index: number): void {
    this.listeners.forEach((l: DataChangeListener) => l.onDataDelete(index))
  }

  private notifyMove(from: number, to: number): void {
    this.listeners.forEach((l: DataChangeListener) => l.onDataMove(from, to))
  }
}

listener 常见回调(名称随 SDK 可能有 onDataAdded / onDataAdd 等别名,以你工程 API 为准):

回调何时用近似 Web
onDataReloaded整表重载换一整页数据
onDataAdd尾部/中间插入push / splice 后补渲染
onDataDelete删除删一行
onDataMove交换/拖拽排序改顺序
onDataChange单条内容变了改字段;常需新 key 才整项重建

getData 保持轻量:滑动会频繁调用。


二、List:最常用的长列表

场景: 消息、设置长表、新闻信息流(等高或近似等高行)。
Web: ul + 虚拟列表。

@Entry
@Component
struct ListLazyDemo {
  private data: BasicDataSource = new BasicDataSource()

  aboutToAppear(): void {
    for (let i = 0; i <= 40; i++) {
      this.data.pushData(`Hello ${i}`)
    }
  }

  build() {
    List({ space: 3 }) {
      LazyForEach(this.data, (item: string) => {
        ListItem() {
          Row() {
            Text(item).fontSize(20)
          }
          .width('100%')
          .padding(12)
        }
        .onClick(() => {
          // 示例:点击追加 —— 必须 pushData + listener,不能只改数组
          this.data.pushData(`Hello ${this.data.totalCount()}`)
        })
      }, (item: string) => item) // key:此处用内容,真实业务用 id
    }
    .width('100%')
    .height('100%')
    .cachedCount(5)
  }
}
注意点说明
子项根须是 ListItem(或自定义组件顶层是 ListItem)
cachedCount可视区上下预建条数;过大吃内存,过小快滑露白
同向嵌套外层 Scroll + 未限高 List → 可能全量加载,懒加载失效
混用不要同一 List 里再塞一堆手写 ListItem + 另一个循环

删除 / 交换:在 onClick 里调 deleteData / moveData,与博客园总结一致——先改数据源,再靠 listener 通知,不要指望 @State 换掉整个 dataSource。


三、ListItemGroup:分组列表里的懒加载

场景: 通讯录按字母、订单按状态、设置按分区。
Web: sticky section / 分组 ul。

ListItemGroup 不能单独当页面根滚动容器,必须落在 List 下。组内再用 LazyForEach 生成 ListItem;预加载数量仍看外层 List 的 cachedCount。

List() {
  // 简化:一组一个 LazyForEach;多组时每组各自数据源,仍避免「一个 List 里叠多个顶层 LazyForEach」的混乱结构
  ListItemGroup({ header: this.groupHeader('A') }) {
    LazyForEach(this.groupA, (name: string) => {
      ListItem() {
        Text(name).padding(12)
      }
    }, (name: string) => name)
  }

  ListItemGroup({ header: this.groupHeader('B') }) {
    LazyForEach(this.groupB, (name: string) => {
      ListItem() {
        Text(name).padding(12)
      }
    }, (name: string) => name)
  }
}
.cachedCount(4)

@Builder
groupHeader(title: string) {
  Text(title)
    .width('100%')
    .padding(8)
    .fontWeight(FontWeight.Bold)
}
注意点说明
归属Group 是 List 的子节点;懒加载语义挂在 List / Group 体系上
ForEach vs LazyGroup + ForEach:组内仍可能一次建齐;Group + LazyForEach:组内按需建、滑出可回收
结构多分组常见「多个 Group,每组内部一个 LazyForEach」;不要在 List 根下再平铺第二个「全局 LazyForEach」和 Group 混战

四、Grid:宫格 / 多列

场景: 相册缩略图、金刚区扩展成可滚宫格、商品双列但等高。
Web: display: grid + 虚拟滚动。

Grid() {
  LazyForEach(this.data, (item: string) => {
    GridItem() {
      Column() {
        Text(item)
      }
      .width('100%')
      .aspectRatio(1)
      .justifyContent(FlexAlign.Center)
      .backgroundColor('#F5F5F5')
    }
  }, (item: string) => item)
}
.columnsTemplate('1fr 1fr 1fr')  // 三列
.rowsGap(8)
.columnsGap(8)
.width('100%')
.height('100%')
.cachedCount(6)
注意点说明
子项根用 GridItem
列模板columnsTemplate 决定列数;和 List 的 lanes 是两套模型
尺寸格子宽高/比例尽量明确,否则可视区计算不准,懒加载易失效
图片宫格务必图片懒加载 + 控尺寸,否则卡的是解码不是 Grid

五、Swiper:轮播页

场景: 引导页、Banner、全屏分页内容。
Web: Swiper / Embla / 横向 snap 分页。

Swiper() {
  LazyForEach(this.data, (item: string) => {
    // 每一页一个根组件;这里直接用 Column 当页,不必套 ListItem
    Column() {
      Text(item).fontSize(24)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }, (item: string) => item)
}
.cachedCount(1)          // 轮播通常缓存更少
.autoPlay(false)
.indicator(true)
.loop(false)             // 海量页 + loop 要谨慎,先搞清数据与 key
注意点说明
子项形态一页一个根;不要在一页里再塞另一个 LazyForEach 长列表(嵌套滚动另论)
cachedCount常比 List 更小(前后各 1 页量级)
数据量Banner 三五页用 ForEach 更简单;页数很多、每页很重时再 LazyForEach
key页内容相似时更要用稳定业务 id,避免滑页错乱

六、WaterFlow:瀑布流

场景: 资讯双列不等高、电商瀑布、兴趣流。
Web: masonry / CSS columns(但 Web 很少自带虚拟化)。

WaterFlow() {
  LazyForEach(this.data, (item: number) => {
    FlowItem() {
      Column() {
        Text(`卡片 ${item}`)
      }
      .width('100%')
      .height(80 + (item % 5) * 30) // 示意不等高
      .backgroundColor('#EEE')
    }
  }, (item: number) => item.toString())
}
.columnsTemplate('1fr 1fr')
.width('100%')
.height('100%')
.cachedCount(4)
.onReachEnd(() => {
  // 触底追加:优先 onDataAdd,不要动不动 onDataReloaded 整表重算
  this.data.pushData(/* 新数据 */)
})

官方实践要点:

注意点说明
子项根用 FlowItem
追加数据尾部 onDataAdd;避免改完数组就 onDataReloaded——瀑布流布局依赖上方节点,整表重载易卡顿
更顺的无限滑可在 onScrollIndex 里距末尾还有 N 条时提前加载,减少触底停顿
不等高高度/宽高比要可计算;缺失尺寸同样会导致懒加载异常
footer可用 WaterFlow({ footer: ... }) 做「加载中」;分组瀑布流时 footer 能力有限制,需看当前 API

七、五容器对照速查

容器典型子项典型场景cachedCount 直觉额外坑
ListListItem长列表约一屏一半~数条同向嵌套 Scroll 失效懒加载
ListItemGroupListItem分组跟外层 List必须在 List 内
GridGridItem宫格可略多于 List(多列)列模板 + 格子尺寸要明确
Swiper页根组件轮播通常很小(如 1)少页不必强上 Lazy
WaterFlowFlowItem瀑布流中等追加用 Add;慎用整表 Reloaded

子组件必须匹配父容器——List 里吐 GridItem、WaterFlow 里吐 ListItem,都会出问题。


八、键值与更新(再钉一次)

8.1 首次渲染

按 keyGenerator 为每条生成唯一 key,再创建子组件。缺省近似:

(item, index) => viewId + '-' + index.toString()

默认带 index:中间插入时后面 key 全变 → 大量重建。业务数据优先:

(item: { id: string }) => item.id

8.2 相同 key

多条数据生成同一个 key 时,框架行为不可预期(缓存取错、滑动错乱)。调试时先查 key,再查数据源。

8.3 非首次:增删移改

操作数据源通知
追加push / 尾插onDataAdd
删除spliceonDataDelete
交换交换元素onDataMove
改一条改字段onDataChange(常需新 key 才整卡重建)
整表换换数组onDataReloaded(瀑布流追加场景慎用)

点击追加 / 删除 / 两次点击交换——与华为云、博客园示例同一套路:交互只调数据源方法,由 listener 驱动 LazyForEach。

8.4 @Reusable

仅 LazyForEach 不够复用节点;复杂卡片把 @Reusable 打在 item 组件上,在 aboutToReuse 换数据。简单一行 Text 收益有限。


九、懒加载失效 / 异常时先查什么

  1. 是不是放在 List / Grid / Swiper / WaterFlow / ListItemGroup 里?
  2. 容器是否给了明确宽高(或主轴约束)?子项是否缺高度导致算不出可视区?
  3. 是否同向嵌套滚动且内层未限高?
  4. 是否一个容器里塞了多个 LazyForEach / 混了大量 ForEach?
  5. 是否重赋值了 dataSource,而不是 listener?
  6. key 是否重复或不稳定?
  7. WaterFlow 追加是否误用了整表 onDataReloaded?

十、建议怎么练

顺序练习过关
1List + LazyForEach + cachedCount,点击追加/删除滑出回收、追加不崩
2两个 ListItemGroup 分组通讯录组头正确、组内懒加载
3Grid 三列相册假数据列齐、快滑不炸内存
4Swiper 少量重页懂「何时不必 Lazy」
5WaterFlow 双列不等高 + 触底/提前加载追加用 Add,滑动少停顿

先把 List 一条线跑顺,再扩 Grid / WaterFlow;Swiper 多数业务用 ForEach 就够,懒加载留给「页很多或单页很重」。