系列:《Web 到 HarmonyOS》· 列表专题续
适合人群:已理解ForEach/LazyForEach差别,准备按场景选型滚动容器
写在前面
LazyForEach 不是「万能 v-for」。它只在支持懒加载的滚动容器里,才会按可视区创建 / 回收子节点;塞进普通 Column / Scroll 套一堆子组件,往往还是一次性全建。
官方明确支持懒加载(可配 cachedCount)的容器:
| 容器 | Web 心智 | 子项根节点通常是 |
|---|---|---|
List | 纵向/横向列表 | ListItem |
ListItemGroup | 分组 section(必须在 List 里) | ListItem |
Grid | CSS Grid / 宫格 | GridItem |
Swiper | 轮播 / 分页滑页 | 单页根组件(常直接内容,不必再套 ListItem) |
WaterFlow | 瀑布流 / Pinterest | FlowItem |
共性铁律(五个容器都适用):
- 容器内只放一个
LazyForEach(不要和大量静态子项 / 另一个 LazyForEach / ForEach 硬拼)。 - 每次迭代只生成一个根子组件,且类型要符合该容器要求。
- 改数据走
DataChangeListener,不要重赋值dataSource。 - key 唯一且稳定;默认 key 带 index,中间插入易错位。
- 父容器主轴尺寸、子项尺寸缺失时,懒加载可能失效(算不出可视区要建几个)。
- 需要节点复用时,把
@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 Lazy | Group + 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 直觉 | 额外坑 |
|---|---|---|---|---|
| List | ListItem | 长列表 | 约一屏一半~数条 | 同向嵌套 Scroll 失效懒加载 |
| ListItemGroup | ListItem | 分组 | 跟外层 List | 必须在 List 内 |
| Grid | GridItem | 宫格 | 可略多于 List(多列) | 列模板 + 格子尺寸要明确 |
| Swiper | 页根组件 | 轮播 | 通常很小(如 1) | 少页不必强上 Lazy |
| WaterFlow | FlowItem | 瀑布流 | 中等 | 追加用 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 |
| 删除 | splice | onDataDelete |
| 交换 | 交换元素 | onDataMove |
| 改一条 | 改字段 | onDataChange(常需新 key 才整卡重建) |
| 整表换 | 换数组 | onDataReloaded(瀑布流追加场景慎用) |
点击追加 / 删除 / 两次点击交换——与华为云、博客园示例同一套路:交互只调数据源方法,由 listener 驱动 LazyForEach。
8.4 @Reusable
仅 LazyForEach 不够复用节点;复杂卡片把 @Reusable 打在 item 组件上,在 aboutToReuse 换数据。简单一行 Text 收益有限。
九、懒加载失效 / 异常时先查什么
- 是不是放在 List / Grid / Swiper / WaterFlow / ListItemGroup 里?
- 容器是否给了明确宽高(或主轴约束)?子项是否缺高度导致算不出可视区?
- 是否同向嵌套滚动且内层未限高?
- 是否一个容器里塞了多个 LazyForEach / 混了大量 ForEach?
- 是否重赋值了
dataSource,而不是 listener? - key 是否重复或不稳定?
- WaterFlow 追加是否误用了整表
onDataReloaded?
十、建议怎么练
| 顺序 | 练习 | 过关 |
|---|---|---|
| 1 | List + LazyForEach + cachedCount,点击追加/删除 | 滑出回收、追加不崩 |
| 2 | 两个 ListItemGroup 分组通讯录 | 组头正确、组内懒加载 |
| 3 | Grid 三列相册假数据 | 列齐、快滑不炸内存 |
| 4 | Swiper 少量重页 | 懂「何时不必 Lazy」 |
| 5 | WaterFlow 双列不等高 + 触底/提前加载 | 追加用 Add,滑动少停顿 |
先把 List 一条线跑顺,再扩 Grid / WaterFlow;Swiper 多数业务用 ForEach 就够,懒加载留给「页很多或单页很重」。