引言

一、技术背景

1.1 鸿蒙列表渲染的核心组件

• data：数据源（数组或可迭代对象）。
• key：唯一标识符（用于优化组件复用，避免不必要的重新渲染）。
• itemGenerator：生成单个列表项的回调函数（接收当前数据和索引）。

1.2 性能瓶颈与虚拟列表的必要性

• 内存占用高：所有列表项的组件实例和 DOM 节点均被创建并保留在内存中。
• 渲染卡顿：首次加载时需要同时渲染大量组件，导致界面冻结或延迟。
• 滚动不流畅：滚动过程中需要频繁计算和更新所有可见及不可见项的布局，消耗大量 CPU 资源。

二、应用使用场景

三、不同场景下的代码实现

3.1 场景1：基础列表渲染（ForEach 循环，ArkTS）

需求描述

代码实现

// BasicList.ets
@Entry
@Component
struct BasicList {
  // 静态数据源
  private contactList: Array<{ name: string, phone: string }> = [
    { name: '张三', phone: '138****1234' },
    { name: '李四', phone: '139****5678' },
    { name: '王五', phone: '150****9012' },
    { name: '赵六', phone: '151****3456' },
    { name: '孙七', phone: '152****7890' }
  ];

  build() {
    Column() {
      // 标题
      Text('联系人列表（基础 ForEach）')
        .fontSize(24)
        .margin({ bottom: 20 })

      // 列表容器（使用 Column 垂直排列）
      Column() {
        ForEach(this.contactList, (contact: { name: string, phone: string }, index: number) => {
          // 单个联系人项
          Row() {
            Text(`${index + 1}. ${contact.name}`)
              .fontSize(18)
              .width('60%')
            Text(contact.phone)
              .fontSize(18)
              .fontColor('#666')
              .width('40%')
          }
          .width('100%')
          .height(50)
          .justifyContent(FlexAlign.SpaceBetween)
          .padding({ left: 10, right: 10 })
          .backgroundColor(index % 2 === 0 ? '#F9F9F9' : '#FFFFFF')
          .margin({ bottom: 5 })
        }, (contact: { name: string, phone: string }) => contact.phone) // key 为唯一标识（电话号码）
      }
      .width('100%')
      .padding(10)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Start)
  }
}

关键点解释

• ForEach参数：
  • data：this.contactList是静态数组，包含联系人信息。
  • key：使用 contact.phone作为唯一标识（确保每个列表项可复用）。
  • itemGenerator：生成每个联系人项的 UI（Row包含姓名和电话）。
• 布局：通过 Column和 Row组合实现垂直列表和水平排列的联系人项。

3.2 场景2：虚拟列表优化（长列表滚动，ArkTS）

需求描述

代码实现

// VirtualList.ets
@Entry
@Component
struct VirtualList {
  // 模拟 1000 条商品数据
  private productList: Array<{ id: number, name: string, price: string }> = [];
  private containerHeight: number = 600; // 列表容器高度
  private itemHeight: number = 80; // 每个列表项的高度
  private visibleCount: number = Math.ceil(this.containerHeight / this.itemHeight); // 可视区域内可见的项数
  private startIndex: number = 0; // 当前可视区域的起始索引
  private endIndex: number = this.visibleCount; // 当前可视区域的结束索引

  aboutToAppear() {
    // 初始化 1000 条商品数据
    for (let i = 0; i < 1000; i++) {
      this.productList.push({
        id: i,
        name: `商品名称 ${i + 1}`,
        price: `¥${(Math.random() * 1000).toFixed(2)}`
      });
    }
  }

  build() {
    Column() {
      // 标题
      Text('虚拟列表优化（长列表滚动）')
        .fontSize(24)
        .margin({ bottom: 20 })

      // 滚动容器（固定高度，内部实现虚拟列表逻辑）
      Scroll() {
        Stack() {
          // 占位容器（用于撑开总高度，模拟所有列表项的存在）
          Rect()
            .width('100%')
            .height(this.productList.length * this.itemHeight)
            .fillColor('transparent')

          // 可视区域容器（仅渲染 startIndex 到 endIndex 的项）
          Stack() {
            ForEach(this.productList.slice(this.startIndex, this.endIndex), (product: { id: number, name: string, price: string }, index: number) => {
              // 计算当前项在可视区域中的实际索引
              const actualIndex = this.startIndex + index;
              ListItem({ product, actualIndex })
            }, (product: { id: number, name: string, price: string }) => product.id.toString()) // key 为商品 ID
          }
          .width('100%')
          .position({ x: 0, y: this.startIndex * this.itemHeight }) // 动态调整位置
        }
        .width('100%')
        .height(this.containerHeight)
        .onScroll((event: ScrollEvent) => {
          // 监听滚动事件，计算新的可视区域索引
          const scrollTop = event.scrollOffsetY;
          this.startIndex = Math.floor(scrollTop / this.itemHeight);
          this.endIndex = Math.min(this.startIndex + this.visibleCount + 2, this.productList.length); // 预加载额外 2 项
        })
      }
      .width('100%')
      .height(this.containerHeight)
    }
    .width('100%')
    .height('100%')
    .padding(10)
  }

  // 单个列表项组件（优化复用）
  @Builder
  ListItem(params: { product: { id: number, name: string, price: string }, actualIndex: number }) {
    Row() {
      Text(`${params.actualIndex + 1}. ${params.product.name}`)
        .fontSize(16)
        .width('70%')
      Text(params.product.price)
        .fontSize(16)
        .fontColor('#FF6B35')
        .width('30%')
        .textAlign(TextAlign.End)
    }
    .width('100%')
    .height(this.itemHeight)
    .padding({ left: 15, right: 15 })
    .backgroundColor(params.actualIndex % 2 === 0 ? '#F9F9F9' : '#FFFFFF')
    .borderRadius(8)
    .margin({ bottom: 5 })
  }
}

关键点解释

• 虚拟列表原理：
  • 占位容器：通过 Rect组件撑开总高度（productList.length * itemHeight），模拟所有列表项的存在，确保滚动条正确显示。
  • 可视区域渲染：仅渲染当前可视区域内的列表项（startIndex到 endIndex），通过 Stack和动态 position调整显示位置。
  • 滚动监听：通过 onScroll事件计算滚动偏移量（scrollOffsetY），动态更新 startIndex和 endIndex，实现按需加载。
• 性能优化：通过复用 ListItem组件（通过 @Builder定义）和仅渲染可见项，大幅降低内存占用和渲染开销。

3.3 场景3：结合 Grid 的虚拟列表（商品网格，ArkTS）

需求描述

代码实现（核心逻辑扩展）

// VirtualGridList.ets（基于 VirtualList.ets 修改）
@Entry
@Component
struct VirtualGridList {
  // ...（数据源和容器高度等参数同 VirtualList）

  build() {
    Column() {
      Text('虚拟网格列表（商品 2 列布局）')
        .fontSize(24)
        .margin({ bottom: 20 })

      Scroll() {
        Stack() {
          // 占位容器（总高度 = 商品总数 / 2 * itemHeight）
          Rect()
            .width('100%')
            .height(Math.ceil(this.productList.length / 2) * this.itemHeight)
            .fillColor('transparent')

          // 可视区域网格容器
          Stack() {
            ForEach(this.productList.slice(this.startIndex, this.endIndex), (product: { id: number, name: string, price: string }, index: number) => {
              const actualIndex = this.startIndex + index;
              GridItemProduct({ product, actualIndex })
            }, (product: { id: number, name: string, price: string }) => product.id.toString())
          }
          .width('100%')
          .position({ x: 0, y: Math.floor(this.startIndex / 2) * this.itemHeight }) // 调整网格位置
        }
        .width('100%')
        .height(this.containerHeight)
        .onScroll((event: ScrollEvent) => {
          const scrollTop = event.scrollOffsetY;
          this.startIndex = Math.floor(scrollTop / this.itemHeight) * 2; // 每 2 项为一组
          this.endIndex = Math.min(this.startIndex + this.visibleCount * 2, this.productList.length);
        })
      }
      .width('100%')
      .height(this.containerHeight)
    }
    .width('100%')
    .height('100%')
    .padding(10)
  }

  // 网格项组件（2 列布局）
  @Builder
  GridItemProduct(params: { product: { id: number, name: string, price: string }, actualIndex: number }) {
    Row() {
      Text(`${params.actualIndex + 1}. ${params.product.name}`)
        .fontSize(14)
        .width('45%')
      Text(params.product.price)
        .fontSize(14)
        .fontColor('#FF6B35')
        .width('45%')
        .textAlign(TextAlign.End)
    }
    .width('100%')
    .height(this.itemHeight)
    .padding(10)
    .backgroundColor(params.actualIndex % 2 === 0 ? '#F9F9F9' : '#FFFFFF')
    .margin({ bottom: 10 })
  }
}

关键点解释

• 网格布局：通过调整 ForEach的分组逻辑（每 2 项为一组）和 position计算，实现 2 列网格的虚拟渲染。
• 性能优化：核心原理与列表虚拟化一致，仅渲染可视区域内的网格项，减少渲染压力。

四、原理解释与核心特性

4.1 列表渲染与虚拟列表的工作流程

sequenceDiagram
    participant User as 用户（滚动/加载）
    participant ForEach as ForEach 组件
    participant Data as 数据源（数组）
    participant Virtualizer as 虚拟列表逻辑（计算可视区域）
    participant Renderer as 渲染引擎

    User->>ForEach: 请求渲染列表（数据源长度 N）
    alt 基础 ForEach（无虚拟化）
        ForEach->>Data: 遍历所有 N 项数据
        Data->>Renderer: 生成 N 个组件实例
        Renderer->>屏幕: 渲染所有组件（内存占用高，滚动卡顿）
    else 虚拟列表（优化后）
        Virtualizer->>Data: 监听滚动事件，计算可视区域索引（startIndex/endIndex）
        Virtualizer->>ForEach: 仅传递可视区域内的数据（如 10~20 项）
        ForEach->>Renderer: 生成少量组件实例（按需渲染）
        Renderer->>屏幕: 仅渲染可视区域组件（内存占用低，滚动流畅）
    end

• 基础 ForEach：直接遍历整个数据源，生成所有列表项的组件实例，导致内存和渲染开销随数据量线性增长。
• 虚拟列表：通过动态计算可视区域索引（基于滚动偏移量），仅渲染当前屏幕可见的列表项（如 10~20 项），其余项通过占位容器模拟存在，极大减少渲染压力。

4.2 核心特性

五、环境准备

5.1 开发工具与项目配置

• 工具：鸿蒙开发工具 DevEco Studio（版本 3.2+）。
• 模板：创建新项目时选择“Empty Ability”模板（基于 ArkTS）。
• 资源目录：列表数据可通过静态数组或网络请求获取（示例中使用静态数据）。

5.2 实际应用示例（完整可运行）

场景：电商商品列表（虚拟列表 + 图片加载）

1. 功能：渲染 1000 个商品项（包含图片、名称、价格），通过虚拟列表优化滚动性能，图片使用懒加载。
2. 代码扩展：在 场景2​ 的基础上，为每个商品项添加 Image组件（加载商品缩略图），并通过 onLoad监听图片加载完成。
3. 运行效果：商品列表滚动流畅，仅当前可视区域的商品项和图片被加载渲染。

六、测试步骤与详细代码

测试1：验证基础列表渲染

1. 步骤：运行 BasicList场景，检查联系人列表是否正确显示（姓名和电话）。
2. 预期：列表项按顺序排列，样式符合预期（如交替背景色）。

测试2：验证虚拟列表性能

1. 步骤：运行 VirtualList场景，快速滚动列表到顶部和底部。
2. 预期：滚动过程流畅无卡顿，控制台无内存警告（通过 DevEco Studio 的 Profiler​ 工具查看内存占用）。

测试3：验证网格虚拟列表

1. 步骤：运行 VirtualGridList场景，检查商品是否以 2 列网格形式显示，滚动是否流畅。
2. 预期：网格布局正确，可视区域外的商品项未实际渲染。

七、部署场景

• 社交应用：好友列表、聊天记录等长列表场景，通过虚拟列表优化滚动性能。
• 电商应用：商品列表、推荐内容等大量数据的展示，提升用户浏览体验。
• 新闻资讯：文章列表、评论区等动态内容，支持快速滚动和加载。

八、疑难解答

8.1 常见问题

8.2 调试技巧

• 性能分析：通过 DevEco Studio 的 Profiler​ 工具查看渲染时间和内存占用，定位性能瓶颈。
• 日志输出：在 ForEach的 itemGenerator中添加 console.log，打印当前渲染的项索引和数据。
• 占位图优化：为网络图片添加占位图（如灰色背景），提升用户体验。

九、未来展望与技术趋势

1. 智能预加载：结合用户滚动行为预测（如即将进入可视区域的项提前加载），进一步优化虚拟列表的响应速度。
2. 跨平台统一：虚拟列表的实现逻辑可能通过统一 API 适配不同平台（如 Android/iOS），降低多平台开发成本。
3. GPU 加速渲染：通过 GPU 加速列表项的布局和绘制，提升高分辨率设备的渲染性能。
4. 动态高度支持：扩展虚拟列表以支持不定高度的列表项（如文本内容动态变化的项），增强灵活性。

十、总结

• 基础 ForEach：通过简单的循环生成列表项，适合小数据量场景（如静态联系人列表）。
• 虚拟列表：通过仅渲染可视区域内的项，大幅提升长列表的滚动流畅性和内存效率（如 1000+ 商品列表）。
• 核心价值：平衡性能与用户体验，支持从简单列表到复杂网格的多样化场景，是鸿蒙应用开发中不可或缺的能力。