摘要

长列表是资讯、笔记、商品等页面高频场景，原生 ForEach 一次性渲染全部数据会造成页面卡顿、内存飙升、滑动掉帧。LazyForEach 实现可视区域按需渲染，只创建屏幕内可见条目，滑出屏幕自动销毁回收，大幅降低内存占用与初始化耗时。API Version23 重构数据迭代器缓存、组件复用、数据刷新监听逻辑，修复低版本列表滑动错乱、数据更新不刷新、条目重复渲染、滚动位置丢失、大量数据 OOM 闪退等兼容缺陷。旧项目升级 API23 后常出现：上千条数据页面打开卡死、上下滑动条目错乱、新增数据列表无变化、返回列表滚动位置重置等问题。本文基于 DevEco Studio 适配 OpenHarmony API23 及以上版本，封装通用数据迭代器、分页加载工具，实现基础懒加载列表、下拉刷新、上拉分页加载三大核心能力，搭配笔记列表、资讯列表两套完整实战代码，输出列表内存复用、数据更新、滚动优化规范，汇总版本升级兼容故障解决方案，为鸿蒙大数据列表开发提供标准化实操模板。

关键词

OpenHarmony；ArkUI；API Version23；LazyForEach；懒加载；长列表；分页加载；高性能列表；数据迭代器

一、引言

1.1 LazyForEach 开发背景

当列表数据量超过 50 条，普通 ForEach 会一次性实例化所有 ListItem 组件，初始化耗时久、占用大量内存，低端设备滑动卡顿、甚至内存溢出闪退。LazyForEach 基于数据迭代器实现按需创建组件：仅渲染当前屏幕可见条目，滑出可视区域立刻销毁释放资源，同时复用条目组件节点，极致优化长列表性能。 OpenHarmony API Version23 针对懒加载底层渲染引擎全面升级，核心变更点：

1. 标准化 IEnumerable 数据迭代器规范，新增数据变更主动通知接口；
2. 优化 ListItem 组件对象池复用逻辑，滑动减少重复创建销毁开销；
3. 修复数据源增删改后列表不刷新、条目顺序错乱 BUG；
4. 完善 Scroll 滚动位置缓存，页面返回保留上次滑动坐标；
5. 区分静态固定数据、动态分页数据两套渲染调度策略；
6. 强化列表资源自动回收，页面退出销毁全部缓存条目组件。

大量 API9~11 旧项目升级后，上千条数据页面加载缓慢、滑动条目内容错乱，根源是未使用 LazyForEach、迭代器未正确触发数据刷新，因此掌握 API23 标准懒加载列表规范是大数据页面必备技能。

1.2 开发环境与测试场景

开发工具：DevEco Studio 5.0 及以上 适配系统：OpenHarmony API Version23、HarmonyOS NEXT 测试场景：千条笔记懒加载列表、下拉刷新重置数据、上拉触底分页加载、列表条目删除 / 新增、页面返回滚动位置保留

二、API23+ LazyForEach 核心概念与 API 说明

2.1 核心组成三要素

1. 数据源迭代器（IEnumerable）：承载数组数据，提供获取数据长度、单条数据、注册数据变更监听能力
2. LazyForEach 组件：懒加载列表容器，接收迭代器、条目构建函数、唯一 key 生成函数
3. ListItem：列表条目，滑出屏幕自动销毁，滑入复用重建

2.2 迭代器 IEnumerable 必须实现方法

ets

// 获取总数据条数
getCount(): number
// 根据索引获取单条数据
getData(index: number): T
// 注册数据变化回调，新增/删除/刷新时通知列表更新
registerDataChangeListener(listener: DataChangeListener): void

2.3 DataChangeListener 数据变更通知方法

1. onDataReloaded ()：全量刷新（下拉刷新重置列表）
2. onDataAdd (index: number)：指定索引新增一条数据
3. onDataDelete (index: number)：指定索引删除一条数据
4. onDataChange (index: number)：指定索引数据内容修改

2.4 LazyForEach 基础语法

ets

LazyForEach(
  迭代器实例,
  (item: 数据类型, index: number) => { ListItem(...) },
  (item: 数据类型, index: number) => item.id.toString() // 唯一key，防止复用错乱
)

2.5 API23 废弃与强制约束

1. 废弃长列表直接使用 ForEach 渲染，数据量大强制使用 LazyForEach；
2. key 生成函数必须返回全局唯一不重复标识，不可使用 index 作为唯一 key；
3. 数据源修改后必须调用对应 DataChangeListener 方法通知列表刷新；
4. ListItem 内部禁止存放全局定时器、长连接，组件频繁销毁重建会造成泄漏；
5. 分页加载需监听 Scroll onScroll 滚动事件，判断触底加载下一页；
6. 页面 aboutToDisappear 清空迭代器数据，释放列表缓存组件内存。

三、API23 标准基础示例代码

3.1 通用可复用数据迭代器模板

ets

import type DataChangeListener from '@ohos.arkui.data.DataChangeListener'

// 通用懒加载迭代器封装
export class ListDataSource<T extends { id: number }> implements IEnumerable<T> {
  private dataArr: T[] = []
  private listener: DataChangeListener | null = null

  // 全量替换数据（下拉刷新）
  reloadData(arr: T[]) {
    this.dataArr = [...arr]
    this.listener?.onDataReloaded()
  }

  // 尾部追加分页数据（上拉加载）
  addData(arr: T[]) {
    const oldLen = this.dataArr.length
    this.dataArr.push(...arr)
    arr.forEach((_, i) => {
      this.listener?.onDataAdd(oldLen + i)
    })
  }

  // 删除指定索引条目
  deleteItem(index: number) {
    this.dataArr.splice(index, 1)
    this.listener?.onDataDelete(index)
  }

  // 修改指定索引条目内容
  updateItem(index: number, newItem: T) {
    this.dataArr[index] = newItem
    this.listener?.onDataChange(index)
  }

  getCount(): number {
    return this.dataArr.length
  }

  getData(index: number): T {
    return this.dataArr[index]
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.listener = listener
  }
}

3.2 最简基础懒加载列表

ets

@Entry
@Component
struct SimpleLazyPage {
  dataSource: ListDataSource<NoteItem> = new ListDataSource()

  aboutToAppear() {
    // 模拟初始化100条测试数据
    const mockList: NoteItem[] = []
    for(let i=0;i<100;i++){
      mockList.push({id:i,title:`笔记${i}`,content:"测试懒加载长列表"})
    }
    this.dataSource.reloadData(mockList)
  }

  build() {
    List({space:10}){
      LazyForEach(
        this.dataSource,
        (item:NoteItem)=>{
          ListItem(){
            Text(item.title).fontSize(16)
          }
        },
        (item)=>item.id.toString()
      )
    }
  }
}

四、三大业务完整实战案例（全兼容 API23）

4.1 实战一：通用分页懒加载工具封装（utils/lazy_list_util.ets）

ets

import type DataChangeListener from '@ohos.arkui.data.DataChangeListener'

// 带id约束的列表实体基类
export interface BaseListItem {
  id: number
}

// 标准懒加载数据源迭代器
export class ListDataSource<T extends BaseListItem> implements IEnumerable<T> {
  private data: T[] = []
  private changeListener: DataChangeListener | null = null

  // 全量覆盖数据，下拉刷新调用
  reload(list: T[]) {
    this.data = [...list]
    this.changeListener?.onDataReloaded()
  }

  // 追加分页数据，上拉触底调用
  append(list: T[]) {
    const startIdx = this.data.length
    this.data.push(...list)
    for (let i = 0; i < list.length; i++) {
      this.changeListener?.onDataAdd(startIdx + i)
    }
  }

  // 删除单条数据
  remove(index: number) {
    this.data.splice(index, 1)
    this.changeListener?.onDataDelete(index)
  }

  // 更新单条数据
  modify(index: number, newItem: T) {
    this.data[index] = newItem
    this.changeListener?.onDataChange(index)
  }

  getCount(): number {
    return this.data.length
  }

  getData(index: number): T {
    return this.data[index]
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.changeListener = listener
  }

  // 清空全部数据，页面销毁调用释放内存
  clear() {
    this.data = []
    this.changeListener?.onDataReloaded()
  }
}

// 分页加载状态枚举
export enum LoadStatus {
  IDLE,     // 空闲
  LOADING,  // 加载中
  NO_MORE   // 无更多数据
}

4.2 实战二：完整笔记懒加载分页列表（下拉刷新 + 上拉加载）

ets

import { ListDataSource, LoadStatus, BaseListItem } from '../utils/lazy_list_util'
import RdbUtil from '../utils/rdb_util'

// 笔记实体
interface NoteItem extends BaseListItem {
  title: string
  content: string
  create_time: number
}

@Entry
@Component
struct LazyNoteListPage {
  // 数据源迭代器
  dataSource: ListDataSource<NoteItem> = new ListDataSource()
  // 分页参数
  pageNum: number = 0
  readonly PAGE_SIZE: number = 10
  @State loadState: LoadStatus = LoadStatus.IDLE
  @State refreshing: boolean = false

  async aboutToAppear() {
    await this.refreshAll()
  }

  // 下拉刷新，重置页码与数据
  async refreshAll() {
    this.pageNum = 0
    this.loadState = LoadStatus.LOADING
    const list = await RdbUtil.queryNoteList(this.pageNum, this.PAGE_SIZE)
    this.refreshing = false
    this.loadState = list.length < this.PAGE_SIZE ? LoadStatus.NO_MORE : LoadStatus.IDLE
    this.dataSource.reload(list)
  }

  // 上拉触底加载下一页
  async loadMore() {
    if (this.loadState !== LoadStatus.IDLE) return
    this.loadState = LoadStatus.LOADING
    this.pageNum += 1
    const list = await RdbUtil.queryNoteList(this.pageNum, this.PAGE_SIZE)
    if (list.length === 0) {
      this.loadState = LoadStatus.NO_MORE
      return
    }
    this.dataSource.append(list)
    this.loadState = list.length < this.PAGE_SIZE ? LoadStatus.NO_MORE : LoadStatus.IDLE
  }

  // 删除单条笔记
  async deleteNote(index: number, id: number) {
    await RdbUtil.deleteNote(id)
    this.dataSource.remove(index)
  }

  build() {
    Column() {
      Text("高性能懒加载笔记列表（LazyForEach）")
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .padding(12)

      List({ space: 12 }) {
        LazyForEach(
          this.dataSource,
          (item: NoteItem, index: number) => {
            ListItem() {
              Row() {
                Column({ space: 4 }).layoutWeight(1) {
                  Text(item.title).fontSize(17).fontWeight(500)
                  Text(item.content).fontSize(14).fontColor("#666")
                }
                Button("删除").backgroundColor("#f56c6c")
                  .onClick(() => this.deleteNote(index, item.id))
              }
              .width("100%")
              .padding(16)
              .backgroundColor(Color.White)
              .borderRadius(10)
            }
          },
          (item) => item.id.toString()
        )

        // 底部加载状态提示
        ListItem() {
          if (this.loadState === LoadStatus.LOADING) {
            Text("正在加载更多笔记...").width("100%").textAlign(TextAlign.Center).padding(10)
          } else if (this.loadState === LoadStatus.NO_MORE) {
            Text("没有更多数据了").width("100%").textAlign(TextAlign.Center).fontColor("#999").padding(10)
          }
        }
      }
      .layoutWeight(1)
      .width("100%")
      .padding({ left: 12, right: 12 })
      .refresh({ refreshing: this.refreshing })
      .onRefresh(async () => await this.refreshAll())
      .onScrollIndex((first, last) => {
        // 滑动到底部触发加载更多
        if (last === this.dataSource.getCount() - 1) {
          this.loadMore()
        }
      })
    }
    .width("100%")
    .height("100%")
    .backgroundColor("#F5F5F5")
  }

  async aboutToDisappear() {
    // 页面退出清空数据源，释放列表缓存组件内存
    this.dataSource.clear()
    await RdbUtil.closeDB()
  }
}

五、API23+ LazyForEach 长列表性能优化规范

5.1 数据源迭代器规范

1. 统一封装 ListDataSource 迭代器，所有列表复用，减少重复代码；
2. 数据增删改必须调用对应 listener 方法，否则列表视图不刷新；
3. 唯一 key 使用业务 id，禁止使用 index 作为 key，防止组件复用时内容错乱。

5.2 条目 ListItem 内存规范

1. ListItem 内部不定义全局定时器、websocket、数据库实例；
2. 条目仅存放临时 UI 状态，持久数据统一存在迭代器数据源；
3. 图片组件设置固定宽高 + objectFit，避免动态宽高造成布局重排卡顿。

5.3 分页加载交互规范

1. 增加 LOADING/NO_MORE 状态锁，防止快速滑动重复触发加载；
2. onScrollIndex 监听底部索引，触底再请求下一页，不预加载过多数据；
3. 下拉刷新执行 reload 全量重置，清空原有页码与列表数据。

5.4 页面内存释放规范

1. 页面aboutToDisappear调用迭代器 clear () 清空全部数据；
2. 长列表页面避免同时开启多个网络轮询，滑动时暂停刷新；
3. 超大列表拆分分页，单页数据控制在 10~20 条，降低单次渲染压力。

六、API23 升级高频兼容问题与解决方案

问题 1：滑动列表条目文字、图片错乱，上下内容互换 解决：key 生成函数使用业务唯一 id，不要用数组索引 index。

问题 2：新增 / 删除数据后列表界面无任何变化 解决：修改数据源后调用对应 onDataAdd/onDataDelete/onDataReloaded 通知刷新。

问题 3：上千条数据页面打开缓慢、黑屏卡顿 解决：替换 ForEach 为 LazyForEach，分页加载而非一次性加载全部数据。

问题 4：快速上下滑动多次重复触发加载更多，请求堆积 解决：增加 LoadStatus 状态锁，加载中禁止再次执行 loadMore。

问题 5：页面退出后列表缓存占用大量内存 解决：aboutToDisappear 调用 dataSource.clear () 清空数据源释放组件缓存。

问题 6：下拉刷新后滚动位置停留在底部，不会回到顶部 解决：调用 reload 全量刷新时重置 pageNum，List 组件自带刷新会自动回弹顶部。

七、总结

LazyForEach 懒加载是 OpenHarmony 处理千级以上长列表的官方高性能方案，API Version23 标准化 IEnumerable 迭代器与数据变更通知机制，优化组件复用池与内存回收逻辑，彻底解决普通 ForEach 一次性渲染造成的卡顿、内存溢出、条目错乱等问题。项目封装通用 ListDataSource 迭代器与分页状态枚举，一套代码可复用在笔记、资讯、商品等所有列表页面，配套下拉刷新、上拉分页、条目删除完整业务逻辑。