摘要

List 是 ArkUI 中承载批量条目数据的核心滚动容器，API Version23 对列表渲染、懒加载逻辑、条目复用、滚动事件回调做底层重构，修复低版本列表卡顿、条目错乱、分页加载失效、底部回弹异常等缺陷；搭配LazyForEach实现可视区域懒加载，是海量资讯、商品、通讯录场景的性能最优方案。低版本 List 代码直接升级 API23 会出现：条目重复渲染、onReachEnd 分页重复触发、列表高度自适应失效、下拉刷新布局偏移、懒加载数据源监听失效等兼容问题。本文基于 DevEco Studio，适配 OpenHarmony API23 及以上版本，讲解 List 核心属性、滚动回调、下拉刷新、分页加载、LazyForEach 标准数据源封装，结合资讯列表、通讯录、商品分页三大实战案例，给出高版本专属性能优化方案，汇总版本升级兼容故障修复方案，为海量数据列表开发提供标准实操模板。

关键词

OpenHarmony；ArkUI；API Version23；List 列表；LazyForEach；懒加载；分页；下拉刷新；性能优化

一、引言

1.1 高版本 List 开发背景

List 容器用于纵向滚动展示批量结构化条目，搭配LazyForEach懒加载仅渲染屏幕可见组件，避免一次性创建上千条目造成内存飙升、页面卡死，是长列表必备优化手段。 OpenHarmony API Version23 重构 List 底层渲染管线：

1. 优化条目复用池逻辑，解决滑动条目内容错乱；
2. 重写onReachEnd、onScroll滚动回调，修复频繁重复触发问题；
3. 规范下拉刷新refresh组件布局约束，消除刷新区域偏移；
4. 强化LazyForEach数据源DataChangeListener监听机制，修复数据刷新不更新列表 bug；
5. 限制 List 嵌套层级，多层 List 嵌套直接给出性能告警。

大量开发者将 API9~11 项目升级至 23 版本后，分页无限循环加载、下拉刷新卡死、懒加载数据变更无响应等问题频发，沿用旧版写法无法满足高版本约束。因此掌握 API23 标准 List 与懒加载开发规范，是资讯、商城、社交类应用核心开发技能。

1.2 开发环境与版本约束

开发工具：DevEco Studio 5.0+ 最低系统版本：OpenHarmony API Version23 开发语言：ArkTS 配套组件：List、ListItem、ListItemGroup、LazyForEach、ICollectionData、DataChangeListener、Scroll、CustomDialog 测试场景：基础静态列表、分组通讯录、下拉刷新列表、上拉分页懒加载、图文商品长列表

二、API23 List 核心 API 与版本变更说明

2.1 List 基础构造参数

List({space: 数值})统一设置 ListItem 垂直间距，单位 vp，API23 自动修正列表首尾边距空白问题。

ets

List({ space: 12 }) {
  // 列表条目
}
.width("100%")
.height("100%")

2.2 核心滚动回调（API23 优化防抖）

1. onScroll：列表滚动实时回调，新增滚动偏移防抖，短时间高频滑动不会重复执行逻辑；
2. onReachEnd()：滚动触底回调，新增触发阈值控制，修复低版本连续多次触发分页请求；
3. onScrollStop：滚动停止后回调，适合图片延迟加载；
4. onItemDragStart/onItemDragEnd：条目拖拽回调，高版本拖拽边界判断更精准。

2.3 下拉刷新 refresh 配置（API23 规范）

ets

.refresh({
  refreshing: this.isRefreshing,
  offset: 60 // 下拉触发距离，API23推荐固定60vp
})
.onRefresh(() => this.refreshData())

版本变更：API23 禁止自定义超大 offset，超过 100vp 会被系统自动截断。

2.4 ListItemGroup 分组列表

用于通讯录、设置分组，API23 修复分组头部固定悬浮失效问题，支持headerSticky参数悬浮吸顶。

ets

ListItemGroup({header: Text("分组标题")})
  .headerSticky(true) // 头部悬浮置顶（API23稳定生效）

2.5 LazyForEach 懒加载 API23 强制规范

懒加载必须自定义类实现ICollectionData接口，重写 4 个标准方法：

1. getTotalCount()：返回数据总条数；
2. getData(index: number)：根据下标返回单条数据；
3. setDataChangeListener(listener)：注册数据变更监听；
4. notifyDataChange()：数据增删改后主动通知列表刷新。

API23 强制要求：数据修改后必须手动调用监听器通知，否则列表不会更新，低版本隐式刷新逻辑全部废弃。

2.6 API23 废弃 / 限制能力

1. 废弃 List 内直接嵌套大量 ForEach，超过 30 条数据编译性能警告，强制使用 LazyForEach；
2. 移除scrollEndOffset模糊阈值，统一标准化 onReachEnd 触发距离；
3. 禁止 List 内部嵌套 List，多层滚动容器会出现滚动冲突；
4. 弱化 ListItem 固定高度自适应，推荐统一固定条目高度减少布局计算。

三、API23 标准基础代码示例

3.1 基础静态 List 列表

ets

@Entry
@Component
struct SimpleListDemo {
  private dataArr: string[] = ["条目1","条目2","条目3","条目4","条目5"]
  build() {
    List({space:10}) {
      ForEach(this.dataArr, (item:string)=>{
        ListItem() {
          Text(item).fontSize(16).padding(16).width("100%")
        }
        .backgroundColor(Color.White)
        .borderRadius(8)
      })
    }
    .width("100%")
    .height("100%")
    .padding(15)
    .backgroundColor("#F5F5F5")
  }
}

3.2 标准 LazyForEach 数据源封装（API23 强制模板）

ets

// 懒加载数据源标准类（API23通用）
class ListDataSource implements ICollectionData {
  private dataList: Array<Object> = []
  private listener: DataChangeListener | null = null

  // 更新全量数据
  setData(list: Object[]) {
    this.dataList = list
    // API23必须手动触发数据变更通知
    this.listener?.onDataReloaded()
  }

  getTotalCount(): number {
    return this.dataList.length
  }

  getData(index: number): Object {
    return this.dataList[index]
  }

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

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

4.1 实战一：下拉刷新 + 上拉分页懒加载资讯列表

ets

@Entry
@Component
struct NewsListPage {
  @State isRefreshing: boolean = false
  @State pageNum: number = 0
  dataSource: ListDataSource = new ListDataSource()

  aboutToAppear() {
    this.loadPageData(0)
  }

  // 刷新重置第一页
  async refreshData() {
    this.isRefreshing = true
    this.pageNum = 0
    await this.loadPageData(0)
    this.isRefreshing = false
  }

  // 分页加载数据
  async loadPageData(page: number) {
    // 模拟接口分页数据
    let tempArr = []
    for(let i=0;i<10;i++){
      tempArr.push({
        id: page*10+i,
        title: `API23资讯第${page*10+i+1}条`,
        desc: "OpenHarmony List懒加载分页实战演示"
      })
    }
    if(page === 0){
      this.dataSource.setData(tempArr)
    }else{
      // 追加分页数据，API23追加需要单独监听增量更新
      let old = this.dataSource.getDataList()
      let newAll = [...old, ...tempArr]
      this.dataSource.setData(newAll)
    }
  }

  build() {
    Column() {
      Text("资讯列表(API23懒加载分页)")
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .padding(15)
      List({ space: 12 }) {
        LazyForEach(this.dataSource, (item:any)=>{
          ListItem() {
            Column({space:6}) {
              Text(item.title).fontSize(17).fontWeight(FontWeight.Medium)
              Text(item.desc).fontSize(14).fontColor("#666")
            }
            .width("100%")
            .padding(14)
            .backgroundColor(Color.White)
            .borderRadius(10)
          }
        })
      }
      .layoutWeight(1)
      .width("100%")
      .padding({left:15,right:15})
      .backgroundColor("#F5F5F5")
      .refresh({refreshing:this.isRefreshing,offset:60})
      .onRefresh(()=>this.refreshData())
      .onReachEnd(()=>{
        this.pageNum++
        this.loadPageData(this.pageNum)
      })
    }
    .width("100%")
    .height("100%")
  }
}

4.2 实战二：分组吸顶通讯录列表（ListItemGroup）

ets

@Entry
@Component
struct ContactListPage {
  build() {
    List({space:10}) {
      ListItemGroup({header:Text("A开头联系人").fontSize(18).padding(10)})
        .headerSticky(true) // 头部悬浮置顶 API23稳定生效
      ListItem() {Text("安安").width("100%").padding(16)}
      ListItem() {Text("阿明").width("100%").padding(16)}

      ListItemGroup({header:Text("B开头联系人").fontSize(18).padding(10)})
        .headerSticky(true)
      ListItem() {Text("白宇").width("100%").padding(16)}
      ListItem() {Text("柏松").width("100%").padding(16)}
    }
    .width("100%")
    .height("100%")
    .padding(15)
  }
}

4.3 实战三：图文商品列表懒加载

ets

@Entry
@Component
struct GoodsListPage {
  dataSource: ListDataSource = new ListDataSource()
  aboutToAppear() {
    let list = []
    for(let i=0;i<20;i++){
      list.push({
        id:i,
        name:`API23开发商品${i+1}`,
        price: 29.9+i,
        desc:"鸿蒙ArkUI高版本实战教程"
      })
    }
    this.dataSource.setData(list)
  }

  build() {
    List({space:14}) {
      LazyForEach(this.dataSource, (item:any)=>{
        ListItem() {
          Row({space:12}) {
            Rect().width(90).height(90).fill("#87CEEB").borderRadius(8)
            Column({space:8}) {
              Text(item.name).fontSize(18).fontWeight(FontWeight.Medium)
              Text(item.desc).fontSize(14).fontColor("#777")
              Text(`￥${item.price}`).fontSize(19).fontColor("#f56c6c")
            }
            .layoutWeight(1)
          }
          .width("100%")
          .padding(12)
          .backgroundColor(Color.White)
          .borderRadius(10)
        }
      })
    }
    .width("100%")
    .height("100%")
    .padding(15)
    .backgroundColor("#F5F5F5")
  }
}

4.4 实战四：列表条目侧滑删除动画（联动 animateTo）

ets

@Entry
@Component
struct ListSlideDelDemo {
  @State slideOffset: number = 0
  build() {
    List() {
      ListItem() {
        Stack() {
          Row() {
            Text("待删除笔记条目").fontSize(16)
          }
          .width("100%")
          .height(72)
          .padding(16)
          .backgroundColor(Color.White)
          .offset({x:this.slideOffset})

          Row() {Text("删除").fontColor(Color.White)}
          .width(80)
          .height("100%")
          .backgroundColor("#f56c6c")
          .position({x:"100%"})
        }
      }
      .onClick(()=>{
        animateTo({duration:280,curve:Curve.EaseOut},()=>{
          this.slideOffset = this.slideOffset === 0 ? -80 : 0
        })
      })
    }
    .width("100%")
    .padding(15)
  }
}

五、API23 专属性能优化规范

1. 海量数据强制使用LazyForEach，禁用 ForEach 渲染超过 30 条数据；
2. ListItem 统一设置固定高度，减少 API23 布局引擎实时尺寸计算开销；
3. 分页加载增加节流控制，onReachEnd 内部增加加载锁，防止重复请求；
4. 列表内部精简组件，移除多层阴影、渐变、嵌套复杂自定义组件；
5. 禁止 List 嵌套 List、Scroll 嵌套 List，高版本会触发滚动冲突；
6. 下拉刷新 offset 统一设 60vp，不使用超大自定义下拉距离；
7. 数据源更新后必须调用onDataReloaded()通知懒加载刷新列表；
8. 图片组件统一设置固定宽高，避免滑动过程中动态宽高引发条目重排。

六、API23 升级常见兼容问题与解决方案

问题 1：分页 onReachEnd 无限重复触发，一次性加载多页数据 解决：增加加载锁标记，请求期间禁止再次执行分页函数；API23 滚动回调防抖失效，需手动加状态拦截。

问题 2：LazyForEach 修改数据后列表无刷新，界面不更新 解决：数据源修改后必须调用this.listener?.onDataReloaded()，低版本自动刷新逻辑已废弃。

问题 3：下拉刷新下拉距离过长，布局被截断 解决：refresh 配置 offset 固定 60，API23 限制最大下拉阈值。

问题 4：滑动列表条目文字、图片错乱复用 解决：ListItem 设置唯一 key，条目内部组件全部固定宽高，减少动态布局。

问题 5：ListItemGroup 头部无法悬浮置顶 解决：添加.headerSticky(true)，API23 默认关闭悬浮，需手动开启。

问题 6：升级后列表滑动卡顿、帧率持续偏低 解决：删除 List 内部多层嵌套 Column/Row，简化条目样式，切换为 LazyForEach 懒加载。

七、总结

本文全部代码严格适配 OpenHarmony API Version23 及以上系统，针对高版本 List 渲染引擎、滚动回调、懒加载数据源、下拉刷新、分组头部做完整适配。List 搭配 LazyForEach 是海量数据列表唯一高性能方案，API23 大幅优化条目复用与内存占用，但同步提高了代码规范约束，旧项目升级必须改造懒加载数据源监听逻辑、分页防抖、刷新参数。

开发长列表遵循三大核心规范：统一固定条目高度、使用懒加载渲染、控制嵌套层级与复杂样式。文中资讯分页、通讯录分组、商品图文、侧滑删除四套业务代码可直接复制使用，配套兼容故障修复方案可用于旧项目升级改造，与前文 Row、Column 线性布局文档构成完整 ArkUI 页面布局开发体系。