HarmonyOS开发：虚拟列表与大数据列表渲染优化

📌 核心要点：当列表数据量达到万级时，一次性渲染所有列表项会让内存和GPU同时崩溃。LazyForEach懒加载+虚拟列表机制只渲染可见区域的列表项，是大数据列表的唯一正确解法。

一、背景与动机

假设你有一个通讯录应用，里面存了10000个联系人。如果用最朴素的ForEach来渲染这个列表，会发生什么？

答案是：应用直接卡死，甚至OOM崩溃。

为什么？因为ForEach会在首次渲染时一次性创建所有列表项的组件。10000个列表项意味着10000个组件实例、10000次测量、10000次布局、10000次绘制。即使每个组件只占1KB内存，10000个就是10MB——这还只是组件对象本身的内存，不算图片、文字等资源。更别提渲染管线要处理10000个节点的遍历了。

这就像你请了10000个工人同时开工，但你的工地只能容纳20个人——剩下的9980个人既干不了活，还占着场地、吃着盒饭。

解决方案就是虚拟列表：只创建和渲染当前可见的列表项（比如屏幕上能显示20个），当用户滑动时，滑出屏幕的列表项被回收，滑入屏幕的列表项被创建或复用。无论数据量是100还是10000，同一时刻在内存中的组件数量始终保持在20个左右。

HarmonyOS通过LazyForEach实现了虚拟列表机制。这篇文章，我们就来深入理解它的工作原理，掌握它的正确用法，并最终实现一个万级数据量的高性能列表。

二、核心原理

2.1 虚拟列表工作机制

flowchart TB
    subgraph 屏幕可视区域
        V1[列表项 3 ✓ 可见]
        V2[列表项 4 ✓ 可见]
        V3[列表项 5 ✓ 可见]
        V4[列表项 6 ✓ 可见]
        V5[列表项 7 ✓ 可见]
    end

    subgraph 预缓存区域
        C1[列表项 1 📦 预缓存]
        C2[列表项 2 📦 预缓存]
        C6[列表项 8 📦 预缓存]
        C7[列表项 9 📦 预缓存]
    end

    subgraph 未加载区域
        U1[列表项 10~10000 ❌ 未加载]
    end

    C1 --> V1 --> V2 --> V3 --> V4 --> V5 --> C6 --> C7 --> U1

    classDef visible fill:#2ECC71,stroke:#27AE60,color:#fff,font-weight:bold
    classDef cached fill:#3498DB,stroke:#2980B9,color:#fff,font-weight:bold
    classDef unloaded fill:#BDC3C7,stroke:#95A5A6,color:#333,font-weight:bold

    class V1,V2,V3,V4,V5 visible
    class C1,C2,C6,C7 cached
    class U1 unloaded

虚拟列表的核心逻辑：

1. 按需加载：只有即将进入可视区域的列表项才会被创建
2. 预缓存：在可视区域上下各预缓存若干个列表项（由cachedCount控制），确保滑动时不会出现白块
3. 回收复用：滑出预缓存区域的列表项被回收到复用池，等待下次复用

2.2 ForEach vs LazyForEach 对比

flowchart LR
    subgraph ForEach
        F1[一次性加载全部数据] --> F2[创建所有组件] --> F3[内存占用高]
        F3 --> F4[首帧耗时长]
    end

    subgraph LazyForEach
        L1[按需加载数据] --> L2[只创建可见组件] --> L3[内存占用低]
        L3 --> L4[首帧耗时短]
    end

    classDef bad fill:#E74C3C,stroke:#C0392B,color:#fff,font-weight:bold
    classDef good fill:#2ECC71,stroke:#27AE60,color:#fff,font-weight:bold

    class F1,F2,F3,F4 bad
    class L1,L2,L3,L4 good

2.3 IDataSource与数据加载流程

sequenceDiagram
    participant List as List组件
    participant DS as IDataSource
    participant Net as 网络/本地数据

    List->>DS: totalCount()
    DS-->>List: 返回数据总量

    List->>DS: getData(index)
    DS-->>List: 返回对应位置数据

    List->>DS: registerDataChangeListener()
    DS-->>List: 注册监听

    Note over Net: 数据变更时
    Net->>DS: 数据更新
    DS->>List: onDataChange() / onDataReloaded()
    List->>DS: 重新获取数据

三、代码实战

3.1 基础示例：LazyForEach基本用法

// 数据模型
interface ContactItem {
  id: string
  name: string
  phone: string
  avatar: string
  department: string
}

// 数据源实现 —— LazyForEach的核心
class ContactDataSource implements IDataSource {
  private contacts: ContactItem[] = []
  private listeners: DataChangeListener[] = []

  constructor(contacts: ContactItem[]) {
    this.contacts = contacts
  }

  // 返回数据总量
  totalCount(): number {
    return this.contacts.length
  }

  // 返回指定位置的数据
  getData(index: number): ContactItem {
    return this.contacts[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)
    }
  }

  // 追加数据
  appendData(newContacts: ContactItem[]): void {
    const startIndex = this.contacts.length
    this.contacts = this.contacts.concat(newContacts)
    // 通知监听器：有新数据插入
    this.listeners.forEach(listener => {
      listener.onDataAdd(startIndex)
    })
  }

  // 刷新全部数据
  refreshData(newContacts: ContactItem[]): void {
    this.contacts = newContacts
    // 通知监听器：数据全部刷新
    this.listeners.forEach(listener => {
      listener.onDataReloaded()
    })
  }
}

@Entry
@Component
struct LazyForEachBasicDemo {
  @State isLoading: boolean = false
  private dataSource: ContactDataSource = new ContactDataSource([])

  aboutToAppear(): void {
    // 初始化数据源
    this.dataSource = new ContactDataSource(this.generateContacts(50))
  }

  // 生成模拟联系人数据
  private generateContacts(count: number): ContactItem[] {
    const names = ['张三', '李四', '王五', '赵六', '钱七', '孙八', '周九', '吴十',
      '郑十一', '冯十二', '陈十三', '褚十四', '卫十五', '蒋十六']
    const depts = ['技术部', '产品部', '设计部', '运营部', '市场部', '人事部']

    return Array.from({ length: count }, (_, i) => ({
      id: `contact_${i}`,
      name: `${names[i % names.length]}${i >= names.length ? i : ''}`,
      phone: `138${String(i).padStart(8, '0')}`,
      avatar: '',
      department: depts[i % depts.length]
    }))
  }

  build() {
    Column() {
      Text('LazyForEach 基础用法')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 16 })

      // 使用LazyForEach渲染列表
      List({ space: 8 }) {
        LazyForEach(
          this.dataSource,
          (contact: ContactItem) => {
            ListItem() {
              Row() {
                // 头像
                Text(contact.name.charAt(0))
                  .width(44)
                  .height(44)
                  .borderRadius(22)
                  .fontSize(18)
                  .fontColor(Color.White)
                  .backgroundColor('#07C160')
                  .textAlign(TextAlign.Center)

                // 信息
                Column() {
                  Text(contact.name)
                    .fontSize(16)
                    .fontWeight(FontWeight.Medium)
                  Text(`${contact.department} · ${contact.phone}`)
                    .fontSize(12)
                    .fontColor(Color.Gray)
                    .margin({ top: 2 })
                }
                .layoutWeight(1)
                .margin({ left: 12 })
                .alignItems(HorizontalAlign.Start)
              }
              .width('100%')
              .padding(12)
              .backgroundColor(Color.White)
              .borderRadius(8)
            }
          },
          (contact: ContactItem) => contact.id  // 唯一标识
        )
      }
      .width('100%')
      .layoutWeight(1)
      .cachedCount(5)  // 预缓存5个列表项

      // 操作按钮
      Row() {
        Button('追加50条')
          .layoutWeight(1)
          .onClick(() => {
            const newContacts = this.generateContacts(50).map((c, i) => ({
              ...c,
              id: `contact_${this.dataSource.totalCount() + i}`,
              name: `${c.name}_新`
            }))
            this.dataSource.appendData(newContacts)
          })

        Button('刷新数据')
          .layoutWeight(1)
          .margin({ left: 12 })
          .onClick(() => {
            this.dataSource.refreshData(this.generateContacts(50))
          })
      }
      .width('100%')
      .margin({ top: 12 })
    }
    .width('100%')
    .height('100%')
    .padding(16)
    .backgroundColor('#F5F5F5')
  }
}

3.2 进阶示例：列表预加载与分页加载

实际项目中，大数据列表通常需要分页从服务端加载数据。这里实现一个"滑到底部自动加载更多"的机制：

import { hiTraceMeter } from '@kit.PerformanceAnalysisKit'

interface PageResult {
  items: ContactItem[]
  hasMore: boolean
  pageIndex: number
}

// 分页数据源
class PagedContactDataSource implements IDataSource {
  private contacts: ContactItem[] = []
  private listeners: DataChangeListener[] = []
  private currentPage: number = 0
  private hasMore: boolean = true
  private isLoading: boolean = false
  private pageSize: number = 30

  constructor() {
    // 初始加载第一页
    this.loadFirstPage()
  }

  private loadFirstPage(): void {
    this.contacts = this.mockFetchPage(0)
    this.currentPage = 0
    this.hasMore = true
  }

  // 模拟分页请求
  private mockFetchPage(page: number): ContactItem[] {
    const names = ['张三', '李四', '王五', '赵六', '钱七', '孙八', '周九', '吴十']
    const depts = ['技术部', '产品部', '设计部', '运营部', '市场部']
    const start = page * this.pageSize

    return Array.from({ length: this.pageSize }, (_, i) => ({
      id: `contact_${start + i}`,
      name: `${names[(start + i) % names.length]}${start + i}`,
      phone: `138${String(start + i).padStart(8, '0')}`,
      avatar: '',
      department: depts[(start + i) % depts.length]
    }))
  }

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

  getData(index: number): ContactItem {
    return this.contacts[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)
    }
  }

  // 加载下一页
  async loadNextPage(): Promise<boolean> {
    if (this.isLoading || !this.hasMore) {
      return false
    }

    this.isLoading = true
    hiTraceMeter.startTrace('load_next_page', 1)

    // 模拟网络延迟
    await new Promise(resolve => setTimeout(resolve, 300))

    this.currentPage++
    const newItems = this.mockFetchPage(this.currentPage)

    // 模拟数据到底
    if (this.currentPage >= 10) {
      this.hasMore = false
    }

    const startIndex = this.contacts.length
    this.contacts = this.contacts.concat(newItems)

    // 通知新增数据
    this.listeners.forEach(listener => {
      listener.onDataAdd(startIndex)
    })

    hiTraceMeter.finishTrace('load_next_page', 1)
    this.isLoading = false
    return this.hasMore
  }

  // 检查是否需要加载更多
  shouldLoadMore(lastVisibleIndex: number): boolean {
    // 当滚动到距离底部5个列表项时触发加载
    return lastVisibleIndex >= this.contacts.length - 5 && this.hasMore && !this.isLoading
  }

  getHasMore(): boolean {
    return this.hasMore
  }

  getIsLoading(): boolean {
    return this.isLoading
  }
}

@Entry
@Component
struct PagedListDemo {
  private dataSource: PagedContactDataSource = new PagedContactDataSource()
  @State showLoadMore: boolean = true
  @State loadingMore: boolean = false

  build() {
    Column() {
      Text('分页加载列表')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 16 })

      List({ space: 8 }) {
        LazyForEach(
          this.dataSource,
          (contact: ContactItem) => {
            ListItem() {
              Row() {
                Text(contact.name.charAt(0))
                  .width(40)
                  .height(40)
                  .borderRadius(20)
                  .fontSize(16)
                  .fontColor(Color.White)
                  .backgroundColor('#3498DB')
                  .textAlign(TextAlign.Center)

                Column() {
                  Text(contact.name)
                    .fontSize(15)
                    .fontWeight(FontWeight.Medium)
                  Text(contact.phone)
                    .fontSize(12)
                    .fontColor(Color.Gray)
                    .margin({ top: 2 })
                }
                .layoutWeight(1)
                .margin({ left: 12 })
                .alignItems(HorizontalAlign.Start)
              }
              .width('100%')
              .padding(12)
              .backgroundColor(Color.White)
              .borderRadius(8)
            }
          },
          (contact: ContactItem) => contact.id
        )

        // 底部加载更多指示器
        ListItem() {
          Row() {
            if (this.loadingMore) {
              LoadingProgress()
                .width(24)
                .height(24)
                .color('#3498DB')
              Text('加载中...')
                .fontSize(14)
                .fontColor(Color.Gray)
                .margin({ left: 8 })
            } else if (!this.showLoadMore) {
              Text('— 已加载全部 —')
                .fontSize(14)
                .fontColor(Color.Gray)
            } else {
              Text('上拉加载更多')
                .fontSize(14)
                .fontColor('#3498DB')
            }
          }
          .width('100%')
          .justifyContent(FlexAlign.Center)
          .padding(16)
        }
      }
      .width('100%')
      .layoutWeight(1)
      .cachedCount(5)
      // 滚动到底部时触发加载
      .onScrollIndex((start: number, end: number) => {
        if (this.dataSource.shouldLoadMore(end)) {
          this.loadingMore = true
          this.dataSource.loadNextPage().then((hasMore: boolean) => {
            this.loadingMore = false
            this.showLoadMore = hasMore
          })
        }
      })
    }
    .width('100%')
    .height('100%')
    .padding(16)
    .backgroundColor('#F5F5F5')
  }
}

3.3 完整示例：万级数据列表实战

将前面的所有技术整合——@Reusable组件复用 + LazyForEach懒加载 + 分页加载 + 预缓存，实现一个10000条数据的高性能列表：

import { hiTraceMeter } from '@kit.PerformanceAnalysisKit'

// 万级数据模型
interface BigDataItem {
  id: string
  title: string
  category: string
  score: number
  tags: string[]
  createdAt: string
}

// 万级数据源
class BigDataDataSource implements IDataSource {
  private items: BigDataItem[] = []
  private listeners: DataChangeListener[] = []
  private allData: BigDataItem[] = []  // 全量数据（模拟本地数据库）
  private loadedCount: number = 0
  private batchSize: number = 100  // 每批加载100条

  constructor() {
    // 模拟10000条数据
    this.allData = this.generateBigData(10000)
    // 初始加载第一批
    this.items = this.allData.slice(0, this.batchSize)
    this.loadedCount = this.batchSize
  }

  // 生成大量模拟数据
  private generateBigData(count: number): BigDataItem[] {
    const categories = ['科技', '财经', '体育', '娱乐', '教育', '健康', '旅游', '美食']
    const tagPool = ['热门', '推荐', '精选', '最新', '独家', '深度', '快讯', '专题']

    return Array.from({ length: count }, (_, i) => ({
      id: `item_${i}`,
      title: `文章标题 ${i} - 这是一篇关于${categories[i % categories.length]}领域的内容`,
      category: categories[i % categories.length],
      score: Math.round((Math.random() * 4 + 1) * 10) / 10,
      tags: [tagPool[i % tagPool.length], tagPool[(i + 3) % tagPool.length]],
      createdAt: new Date(Date.now() - i * 3600000).toISOString()
    }))
  }

  totalCount(): number {
    return this.allData.length  // 返回全量数据总数
  }

  getData(index: number): BigDataItem {
    // 按需加载：如果请求的数据还未加载到items中，动态扩展
    if (index >= this.items.length && index < this.allData.length) {
      const newEnd = Math.min(index + this.batchSize, this.allData.length)
      this.items = this.items.concat(this.allData.slice(this.items.length, newEnd))
      this.loadedCount = this.items.length
    }
    return this.items[index] || this.allData[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)
    }
  }

  getLoadedCount(): number {
    return this.loadedCount
  }

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

// 复用列表项组件
@Reusable
@Component
struct ReusableBigDataItem {
  @Prop item: BigDataItem | null = null

  aboutToReuse(params: Record<string, Object>): void {
    // 复用时无需额外操作，@Prop会自动更新
  }

  aboutToRecycle(): void {
    // 清理临时状态
  }

  // 格式化时间
  private formatDate(isoStr: string): string {
    const date = new Date(isoStr)
    return `${date.getMonth() + 1}月${date.getDate()}日 ${date.getHours()}:${String(date.getMinutes()).padStart(2, '0')}`
  }

  build() {
    if (!this.item) {
      return
    }

    Column() {
      Row() {
        // 分类标签
        Text(this.item.category)
          .fontSize(11)
          .fontColor(Color.White)
          .padding({ left: 6, right: 6, top: 2, bottom: 2 })
          .backgroundColor('#3498DB')
          .borderRadius(4)

        // 评分
        Text(`★ ${this.item.score}`)
          .fontSize(11)
          .fontColor('#FFB800')
          .margin({ left: 8 })

        Blank()

        // 时间
        Text(this.formatDate(this.item.createdAt))
          .fontSize(11)
          .fontColor('#999999')
      }
      .width('100%')

      // 标题
      Text(this.item.title)
        .fontSize(15)
        .fontWeight(FontWeight.Medium)
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
        .margin({ top: 6 })

      // 标签
      Row() {
        ForEach(this.item.tags, (tag: string) => {
          Text(`#${tag}`)
            .fontSize(11)
            .fontColor('#666666')
            .padding({ left: 4, right: 4, top: 2, bottom: 2 })
            .backgroundColor('#F0F0F0')
            .borderRadius(4)
            .margin({ right: 4 })
        }, (tag: string) => tag)
      }
      .margin({ top: 6 })
    }
    .width('100%')
    .padding(12)
    .backgroundColor(Color.White)
    .borderRadius(8)
  }
}

@Entry
@Component
struct BigDataListDemo {
  private dataSource: BigDataDataSource = new BigDataDataSource()
  @State scrollOffset: number = 0
  @State fps: number = 0
  private lastFrameTime: number = Date.now()
  private frameCount: number = 0

  aboutToAppear(): void {
    hiTraceMeter.startTrace('big_data_list_init', 1)
    console.info(`[万级列表] 数据总量: ${this.dataSource.getTotalCount()}`)
    console.info(`[万级列表] 初始加载: ${this.dataSource.getLoadedCount()}条`)
  }

  build() {
    Column() {
      // 标题栏 + 性能指标
      Row() {
        Column() {
          Text('万级数据列表')
            .fontSize(22)
            .fontWeight(FontWeight.Bold)
          Text(`共${this.dataSource.getTotalCount()}条数据，已加载${this.dataSource.getLoadedCount()}条`)
            .fontSize(12)
            .fontColor(Color.Gray)
            .margin({ top: 2 })
        }
        .alignItems(HorizontalAlign.Start)
        .layoutWeight(1)

        // 性能指标
        Column() {
          Text('滑动帧率')
            .fontSize(10)
            .fontColor(Color.Gray)
          Text(`${this.fps} FPS`)
            .fontSize(16)
            .fontWeight(FontWeight.Bold)
            .fontColor(this.fps >= 55 ? '#2ECC71' : this.fps >= 45 ? '#F39C12' : '#E74C3C')
        }
        .alignItems(HorizontalAlign.Center)
      }
      .width('100%')
      .margin({ bottom: 12 })

      // 万级数据列表
      List({ space: 8 }) {
        LazyForEach(
          this.dataSource,
          (item: BigDataItem) => {
            ListItem() {
              ReusableBigDataItem({ item: item })
            }
          },
          (item: BigDataItem) => item.id
        )
      }
      .width('100%')
      .layoutWeight(1)
      .cachedCount(8)  // 预缓存8个列表项，确保滑动流畅
      .onScroll(() => {
        // 简易帧率计算
        this.frameCount++
        const now = Date.now()
        if (now - this.lastFrameTime >= 1000) {
          this.fps = this.frameCount
          this.frameCount = 0
          this.lastFrameTime = now
        }
      })

      // 底部信息
      Text('↑ 上下滑动体验万级数据列表 ↑')
        .fontSize(12)
        .fontColor(Color.Gray)
        .margin({ top: 8 })
    }
    .width('100%')
    .height('100%')
    .padding(16)
    .backgroundColor('#F5F5F5')
  }
}

四、踩坑与注意事项

坑点1：LazyForEach的keyGenerator返回不稳定的值

keyGenerator（第三个参数）必须为每个数据项返回稳定且唯一的标识。如果返回值不稳定，LazyForEach会认为数据发生了变化，触发不必要的组件重建：

// ❌ 错误：index作为key，数据变更后key错位
LazyForEach(
  this.dataSource,
  (item: DataItem) => { ... },
  (item: DataItem, index?: number) => `${index}`  // index不稳定！
)

// ✅ 正确：使用数据的唯一ID
LazyForEach(
  this.dataSource,
  (item: DataItem) => { ... },
  (item: DataItem) => item.id  // 稳定的唯一标识
)

坑点2：IDataSource的getData中执行耗时操作

getData方法在列表项进入可视区域时被频繁调用。如果在这里执行网络请求、数据库查询等耗时操作，会直接阻塞UI线程：

// ❌ 错误：getData中执行耗时操作
getData(index: number): DataItem {
  return this.loadFromDatabase(index)  // 同步数据库查询，阻塞UI！
}

// ✅ 正确：getData只返回已加载的数据，异步加载通过通知机制更新
getData(index: number): DataItem {
  if (index < this.loadedItems.length) {
    return this.loadedItems[index]
  }
  // 返回占位数据
  return this.getPlaceholder(index)
  // 异步加载在后台进行，完成后通知更新
}

坑点3：cachedCount设置过大导致内存压力

cachedCount越大，预缓存的列表项越多，滑动越流畅，但内存占用也越高。需要根据列表项的复杂度和设备性能找到平衡点：

// ⚠️ cachedCount过大：每个列表项10KB，cachedCount=50就是500KB
List().cachedCount(50)  // 内存压力大

// ✅ 根据列表项大小调整
// 简单列表项（纯文字）：cachedCount = 5~10
// 中等列表项（文字+图片）：cachedCount = 3~5
// 复杂列表项（多图+交互）：cachedCount = 2~3
List().cachedCount(5)

坑点4：LazyForEach与@State数据混用

LazyForEach使用IDataSource管理数据，不应该再通过@State驱动更新。两者混用会导致数据不一致：

// ❌ 错误：同时用@State和IDataSource管理同一份数据
@State items: DataItem[] = []
private dataSource: MyDataSource = new MyDataSource(this.items)

// 修改@State不会通知dataSource
this.items.push(newItem)  // dataSource不知道数据变了！

// ✅ 正确：统一通过dataSource管理数据
private dataSource: MyDataSource = new MyDataSource()

// 通过dataSource的方法修改数据
this.dataSource.addItem(newItem)  // 内部通知监听器

坑点5：列表项高度不一致导致滚动位置跳动

LazyForEach在计算滚动偏移时，如果列表项高度不一致，可能出现滚动位置跳动。建议对高度差异大的列表项进行分组，或使用固定高度：

// ⚠️ 高度不一致的列表项
LazyForEach(this.dataSource, (item: DataItem) => {
  ListItem() {
    if (item.type === 'text') {
      Text(item.content).padding(12)  // 高度约50
    } else {
      Image(item.imageUrl).height(200)  // 高度200
    }
  }
})

// ✅ 优化：统一列表项高度，或使用固定高度的容器
LazyForEach(this.dataSource, (item: DataItem) => {
  ListItem() {
    Column() {
      Text(item.content).padding(12)
      if (item.type === 'image') {
        Image(item.imageUrl).height(120)  // 固定图片高度
      }
    }
    .minHeight(60)  // 设置最小高度
  }
})

坑点6：忘记在组件销毁时注销IDataSource监听器

如果IDataSource的生命周期比List组件长，List组件销毁时必须注销监听器，否则会造成内存泄漏：

// IDataSource的unregisterDataChangeListener会在List销毁时自动调用
// 但如果你在自定义逻辑中注册了额外的监听器，需要手动注销

aboutToDisappear(): void {
  // 如果有自定义的监听器注册，在这里注销
  this.dataSource.unregisterDataChangeListener(this.customListener)
}

五、HarmonyOS 6适配说明

API差异表

行为变更

1. LazyForEach预加载策略优化：HarmonyOS 6根据滑动速度动态调整预加载数量，快速滑动时自动增加预缓存
2. 列表项回收策略：从FIFO改为LRU，最近使用的列表项优先保留在缓存中
3. 异步布局：列表项的测量和布局可以在后台线程执行，不阻塞UI线程

适配代码

import { hiTraceMeter } from '@kit.PerformanceAnalysisKit'

@Entry
@Component
struct HarmonyOS6VirtualListAdaptation {
  private dataSource: BigDataDataSource = new BigDataDataSource()
  @State scrollVelocity: number = 0

  // 根据滑动速度动态调整cachedCount
  private getAdaptiveCachedCount(): number {
    if (this.scrollVelocity > 3000) {
      return 12  // 快速滑动：增加预缓存
    } else if (this.scrollVelocity > 1000) {
      return 8   // 中速滑动
    }
    return 5     // 慢速/静止：减少预缓存，节省内存
  }

  build() {
    Column() {
      Text('HarmonyOS 6 虚拟列表适配')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 16 })

      // 性能指标
      Row() {
        Text(`数据总量: ${this.dataSource.getTotalCount()}`)
          .fontSize(13)
          .fontColor(Color.Gray)
        Text(` | 滑动速度: ${this.scrollVelocity}`)
          .fontSize(13)
          .fontColor(Color.Gray)
        Text(` | 缓存数: ${this.getAdaptiveCachedCount()}`)
          .fontSize(13)
          .fontColor('#3498DB')
      }
      .width('100%')
      .margin({ bottom: 12 })

      List({ space: 8 }) {
        LazyForEach(
          this.dataSource,
          (item: BigDataItem) => {
            ListItem() {
              ReusableBigDataItem({ item: item })
            }
          },
          (item: BigDataItem) => item.id
        )
      }
      .width('100%')
      .layoutWeight(1)
      .cachedCount(this.getAdaptiveCachedCount())
      .onScrollFrame((offset: number) => {
        // HarmonyOS 6: 获取滑动速度
        this.scrollVelocity = Math.abs(offset) * 60  // 近似帧率换算
        return { offsetRemain: offset }
      })

      Text('↑ 滑动体验优化后的万级列表 ↑')
        .fontSize(12)
        .fontColor(Color.Gray)
        .margin({ top: 8 })
    }
    .width('100%')
    .height('100%')
    .padding(16)
    .backgroundColor('#F5F5F5')
  }
}

六、总结

三维度评价表

虚拟列表的核心思想可以用一句话概括：只渲染用户看得见的东西。

这听起来理所当然，但在实际开发中，很多开发者还是会不自觉地用ForEach去渲染几百上千条数据，然后纳闷"为什么列表这么卡"。记住一个简单的判断标准：数据量超过100条，就用LazyForEach。这不是什么"过度优化"，而是基本的工程规范。

另外，虚拟列表不是银弹。如果你的列表项本身就很重（比如每个列表项有大量图片、复杂动画），即使用了LazyForEach，滑动时仍然可能卡顿。这时候需要结合@Reusable组件复用、图片懒加载、布局扁平化等手段综合优化。性能优化从来不是单一技术能解决的，它是一个系统工程——而虚拟列表，是这个工程的地基。