《Web 到 HarmonyOS》-- 列表与性能:v-for → ForEach / LazyForEach

0 阅读7分钟

系列:《Web 到 HarmonyOS》· 列表专题
适合人群:会 Vue v-for / :key / 虚拟列表,准备写流畅的鸿蒙列表


写在前面

Web 里列表常常是:ul + v-for,卡了再上虚拟列表库;下拉刷新、触底加载靠业务自己拼。

鸿蒙把「容器结构 / 循环渲染 / 虚拟化与回收 / 刷新加载」拆成几层能力。前端心智可以这样对齐:

你想做的事鸿蒙近似 Web
可滚动列表容器List带滚动的列表容器,不是随便套 div
分组ListItemGroup通讯录按字母、商品按分类
一行数据ListItem一条 li / 一张卡片根节点
少~中量循环ForEachv-for
海量 + 更彻底回收LazyForEach虚拟列表 + 节点回收
复杂/条件行模板@Builder抽成子组件或 v-if 分支模板
下拉刷新refreshable手势库 / 组件库的 pull-refresh
触底加载onReachEndIntersectionObserver / 滚动到底

选型一句话: 设置页、几十条以内 → List + ForEach;新闻流、商品流、可能上千上万 → 优先想 LazyForEach + 分页,并配合轻量 item、@Reusable、图片懒加载。


一、List 三层结构(先别急着写 v-for)

ArkUI 里列表不是「Column 里堆一堆 Text」,而是固定三层:

List                    ← 根容器:方向、列数、滚动、分隔线
 ├─ ListItemGroup?      ← 可选分组
 └─ ListItem            ← 每一行(直接子节点必须是 ListItem 或 Group)
      └─ 你的内容 / 自定义组件
层级管什么Web 对照
List竖/横滚、多列 lanes、分隔线、刷新/触底列表壳子 + 滚动策略
ListItemGroup分组标题与分段sticky section / 分组 header
ListItem一条记录的根单行卡片根节点

主轴未设死尺寸时,List 会自适应:子项总高度小于父级则跟着子项走;超出则占满父级并出现滚动——和「外层定高、内层溢出滚动」的 Web 习惯类似,但规则写在组件自身上。


二、数据绑定:ForEach 与 @Builder

2.1 ForEach ≈ v-for(中小数据首选)

社区实践里,数据量不大(常见说法:千条以内量级) 用 ForEach 即可,写法最接近 Vue:

@Entry
@Component
struct NewsList {
  @State newsData: Array<NewsItemModel> = []

  build() {
    List() {
      ForEach(this.newsData, (news: NewsItemModel) => {
        ListItem() {
          NewsItem({ news: news })
        }
      }, (news: NewsItemModel) => news.id.toString()) // Key,必写稳
    }
  }
}

@Component
struct NewsItem {
  @Prop news: NewsItemModel = new NewsItemModel()

  build() {
    Row() {
      Text(this.news.title).fontSize(16)
    }
    .padding(10)
  }
}
VueArkUI
v-for="news in newsData"ForEach(this.newsData, ...)
:key="news.id"第三个参数 news.id.toString()
子组件 props@Prop / 自定义组件入参
省略 key / 用 index排序、插入时错位与多余重建

补充:ForEach 数据源可以是数组,也可以是 Set / Map 等可迭代对象(业务里仍以数组最常见)。

2.2 Key 三条硬规则(和 Vue 同一铁律,执行更严)

  1. 唯一:整表生命周期内每条一个不同 key。
  2. 稳定:优先数据库主键、业务 ID、UUID;不要用数组 index,也不要用每次渲染新算的随机数。
  3. 简单:字符串或数字即可,别拿复杂对象当 key。

Key 错了:状态串行、滚动复用错乱、性能掉——ArkUI 靠 key 认「是不是同一行」。

// ❌
(item, index) => index.toString()

// ✅
(item) => item.id.toString()

2.3 @Builder:条件行 / 复杂行模板

Web 里你会把「重要新闻红字、普通黑字」拆成小组件或 v-if。鸿蒙可用 @Builder 提高可读性与复用:

@Builder
function buildNewsItem(news: NewsItemModel) {
  if (news.type === 'important') {
    ListItem() {
      Text(news.title)
        .fontColor(Color.Red)
        .fontWeight(FontWeight.Bold)
    }
  } else {
    ListItem() {
      Text(news.title).fontColor(Color.Black)
    }
  }
}

List() {
  ForEach(this.newsData, (news: NewsItemModel) => {
    buildNewsItem(news)
  }, (news: NewsItemModel) => news.id.toString())
}

行结构复杂、分支多时:优先「自定义组件 + @Prop」;分支样式简单时用 @Builder 就够。


三、性能:虚拟化、LazyForEach、分页与图片

数据一大,一次建满所有行会:首屏卡、内存高、滑动掉帧。按优先级处理。

3.1 List 自带虚拟化(ForEach 也不等于「浏览器里全量 DOM」)

API 9 起,List 对 ForEach 已有内置虚拟滚动思路(和「裸 Column + ForEach 全堆」不同):

阶段行为(理解用)
初始化优先创建、布局可视区内的 ListItem
空闲预加载范围内的项再补布局
更远更外围项更「轻」,内部子树不必全建满

所以:短~中列表 用 List + ForEach 往往已经比 Web 裸 v-for 省心。
但仍要注意:ForEach 模式下,滑出可视区的项通常不会像 LazyForEach 那样销毁回收,内存会随数据规模持续抬升。海量场景仍要升级策略。

(极特殊:行极高、自研滚动逻辑时,才考虑手动「占位总高 + 只渲染 visible 窗口」——多数业务用不到,优先官方 List / LazyForEach。)

3.2 LazyForEach:海量数据的彻底回收

万级以上、新闻/电商长列表,用 LazyForEach:

ForEach(在 List 里)LazyForEach
创建可视 + 预加载等策略按需迭代数据源
滑出预加载区项多半仍占着可销毁;带 @Reusable 的可进复用池
数据源@State 数组等实现 IDataSource,改数据走 listener
近似 Web加强版 v-for虚拟列表 + 回收

约束(踩坑高频):

  • 懒加载预期落在 List / Grid / Swiper / WaterFlow / ListItemGroup 等容器;嵌套同向滚动且未限高时,可能全量加载,懒加载失效。
  • 一个容器里不要硬拼多个 LazyForEach,也不要和大量静态 ListItem / ForEach 混用。
  • 每次迭代只出一个子组件根;key 同样要唯一稳定。
  • 不要靠重赋值整个 dataSource 指望刷新;用 onDataAdd / onDataDelete / onDataChange / onDataReloaded。

最小数据源骨架:

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

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

  getData(index: number): NewsItemModel {
    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)
    }
  }

  setData(data: NewsItemModel[]): void {
    this.list = data
    this.listeners.forEach((l: DataChangeListener) => l.onDataReloaded())
  }

  append(items: NewsItemModel[]): void {
    const start = this.list.length
    this.list = this.list.concat(items)
    this.listeners.forEach((l: DataChangeListener) => {
      // 按实际 API 选用批量增加或逐条 onDataAdd
      l.onDataAdd(start)
    })
  }
}
List() {
  LazyForEach(this.dataSource, (item: NewsItemModel) => {
    ListItem() {
      NewsItem({ news: item })
    }
  }, (item: NewsItemModel) => item.id.toString())
}
.width('100%')
.height('100%')
.cachedCount(4)

getData 保持轻量:滑动时会频繁调用,重计算 / 同步 IO 会直接变成掉帧。

3.3 cachedCount:预加载缓冲

可视区上下再缓存若干项,减轻「快速滑露白」。

建议说明
约一屏条数的一半官方常见量级
复杂卡片 3~5实战折中
过大首屏与内存变差
过小快滑露白、掉帧

3.4 列表项与图片

  • 轻量 ListItem:少深层嵌套、少在 build 里算重活。
  • 图片:Image 使用懒加载(如 .lazyLoad(true)),非可视区不急着解码;再配合合适尺寸、格式与缓存。
  • @Reusable:复杂卡片进出屏时复用节点,在 aboutToReuse 换数据;一行纯文字收益有限。
  • 状态下沉:选中、展开放在 item 自己的 @State,别让父组件一大坨 @State 改一行刷整表。
  • 滚动中:少改全局状态,避免整树无效刷新。

3.5 分页:虚拟化管「怎么画」,分页管「怎么要数据」

Web 信息流 = 虚拟列表 + loadMore。鸿蒙同样:渲染层用 ForEach/LazyForEach,数据层用分页。

@Component
struct PaginatedList {
  @State data: NewsItemModel[] = []
  @State currentPage: number = 1
  @State hasMore: boolean = true
  @State isLoading: boolean = false

  private async loadMore(): Promise<void> {
    if (this.isLoading || !this.hasMore) {
      return
    }
    this.isLoading = true
    try {
      const page = await fetchPage(this.currentPage)
      if (page.length > 0) {
        this.data = this.data.concat(page)
        this.currentPage++
      } else {
        this.hasMore = false
      }
    } finally {
      this.isLoading = false
    }
  }

  build() {
    List() {
      ForEach(this.data, (item: NewsItemModel) => {
        ListItem() {
          NewsItem({ news: item })
        }
      }, (item: NewsItemModel) => item.id.toString())
    }
    .onReachEnd(() => {
      this.loadMore()
    })
  }
}

isLoading 防连触;hasMore 防空刷;失败时记得回退页码(见下一节完整示例思路)。


四、标配交互:下拉刷新 + 上拉加载

移动端列表标配,鸿蒙用组件能力接,不必从零造手势。

4.1 下拉刷新:refreshable

刷新是替换数据,不是追加:

@State data: NewsItemModel[] = []
@State isRefreshing: boolean = false

private async handleRefresh(): Promise<void> {
  this.isRefreshing = true
  try {
    this.data = await fetchLatestData()
  } finally {
    this.isRefreshing = false
  }
}

List() {
  ForEach(this.data, (item: NewsItemModel) => {
    ListItem() { /* ... */ }
  }, (item: NewsItemModel) => item.id.toString())
}
.refreshable({
  onRefresh: () => {
    this.handleRefresh()
  }
  // 视 API 版本还可配触发距离、阻力等
})

对照 Web:onRefresh ≈ pull-refresh 的回调;isRefreshing 控指示器显隐。

4.2 上拉加载:onReachEnd

触底 ≈ Web 的 infinite scroll。与刷新组合时记住:

操作数据怎么变页码
下拉刷新整表替换重置为 1,hasMore = true
触底加载尾部追加currentPage++,失败则回退

完整状态机建议:

  1. isLoading:进行中拒绝重入。
  2. hasMore:本页不足 pageSize 则视为没有更多。
  3. 底部 UI:正在加载… / 没有更多了。
  4. 失败:Toast + 页码回退,避免空洞页号。

五、布局与多设备

List()
  .listDirection(Axis.Vertical)   // 或 Horizontal
  .lanes(2)                       // 多列(竖列表时常用来做双列卡片)
  .alignListItem(ListItemAlign.Center)
  .divider({
    strokeWidth: 1,
    color: '#F0F0F0',
    startMargin: 20,
    endMargin: 20
  })
  .scrollBar(BarState.Auto)
能力用途Web 对照
listDirection横滑/竖滑flex-direction + 横向 scroll
lanes多列CSS multi-column / 网格
divider分隔线border-bottom
scrollBar滚动条显隐OS / CSS overlay scroll

多设备:按屏宽动态 lanes(例如宽屏 2 列、窄屏 1 列),和 Web 响应式「断点改列数」同一思路。


六、常见坑与对策

现象优先怀疑对策
滚动时整表狂刷状态粒度太大状态下沉到 item;少动全局 @State
图多就卡同步解码大图lazyLoad、压尺寸、缓存
中间插入后错乱key 用了 index业务唯一 id
懒加载没生效同向嵌套 Scroll、List 未限高单层 List;分组用 ListItemGroup
LazyForEach 不更新重赋值了 dataSourcelistener 通知增删改
触底连打接口没闸门isLoading + hasMore
复杂手势/动画卡主线程过重减树深;热路径考虑更轻绘制方式