核心优势

对比ForEach全量渲染模式，LazyForEach可提升首屏渲染速度80%以上，降低内存占用70%，支持百万级数据列表的流畅滚动，是企业级长列表开发的首选方案。

严禁行为

严禁使用数组索引作为Key，严禁使用JSON.stringify(item)生成Key，这两种方式会导致组件无法复用、渲染错乱和严重性能问题。

// BasicDataSource.ets
import { IDataSource, DataChangeListener } from '@kit.ArkUI';

// 数据模型定义
export class Product {
  id: string;
  name: string;
  price: string;
  imageUrl: string;

  constructor(id: string, name: string, price: string, imageUrl: string) {
    this.id = id;
    this.name = name;
    this.price = price;
    this.imageUrl = imageUrl;
  }
}

// 通用数据源基类
export class BasicDataSource implements IDataSource { private dataArray: T[] = []; private listeners: DataChangeListener[] = []; // --- IDataSource 必须实现的方法 --- /** * 获取数据总条数 * @returns 数据总数 */ public totalCount(): number { return this.dataArray.length; } /** * 获取指定索引的数据项 * @param index 索引位置 * @returns 数据项 */ public getData(index: number): T { return this.dataArray[index]; } /** * 注册数据变更监听器 * @param listener 监听器实例 */ public registerDataChangeListener(listener: DataChangeListener): void { if (!this.listeners.includes(listener)) { this.listeners.push(listener); } } /** * 注销数据变更监听器 * @param listener 监听器实例 */ public unregisterDataChangeListener(listener: DataChangeListener): void { const pos = this.listeners.indexOf(listener); if (pos >= 0) { this.listeners.splice(pos, 1); } } // --- 公共数据操作方法 --- /** * 重置数据（全量刷新） * @param data 新的数据集 */ public resetData(data: T[]): void { this.dataArray = data; this.notifyDataReload(); } /** * 追加数据（分页加载） * @param data 要追加的数据集 */ public addData(data: T[]): void { const startIndex = this.dataArray.length; this.dataArray.push(...data); this.notifyDataAdd(startIndex, data.length); } /** * 插入数据到指定位置 * @param index 插入位置 * @param data 要插入的数据 */ public insertData(index: number, data: T): void { if (index >= 0 && index <= this.dataArray.length) { this.dataArray.splice(index, 0, data); this.notifyDataAdd(index, 1); } } /** * 删除指定索引的数据 * @param index 要删除的索引位置 */ public deleteData(index: number): void { if (index >= 0 && index < this.dataArray.length) { this.dataArray.splice(index, 1); this.notifyDataDelete(index); } } /** * 更新指定索引的数据 * @param index 要更新的索引位置 * @param newData 新的数据项 */ public updateData(index: number, newData: T): void { if (index >= 0 && index < this.dataArray.length) { this.dataArray[index] = newData; this.notifyDataChange(index); } } /** * 获取全部数据（用于业务逻辑处理） * @returns 全部数据数组 */ public getAllData(): T[] { return [...this.dataArray]; // 返回副本，防止外部直接修改 } // --- 内部通知方法 --- /** * 通知全量数据刷新 */ private notifyDataReload(): void { this.listeners.forEach(listener => listener.onDataReloaded()); } /** * 通知数据新增 * @param startIndex 新增起始索引 * @param count 新增数量 */ private notifyDataAdd(startIndex: number, count: number): void { this.listeners.forEach(listener => { for (let i = 0; i < count; i++) { listener.onDataAdd(startIndex + i); } }); } /** * 通知数据删除 * @param index 删除的索引位置 */ private notifyDataDelete(index: number): void { this.listeners.forEach(listener => listener.onDataDelete(index)); } /** * 通知数据变更 * @param index 变更的索引位置 */ private notifyDataChange(index: number): void { this.listeners.forEach(listener => listener.onDataChange(index)); } }

// ProductListItem.ets
import { Product } from './BasicDataSource';

@Reusable
@Component
export struct ProductListItem {
  @State product: Product = new Product('', '', '', '');

  /**
   * 组件复用时调用，更新组件数据
   * @param params 新的参数对象
   */
  aboutToReuse(params: ESObject) {
    this.product = params.item as Product;
    // 清理组件内部状态，避免复用错乱
    // 例如：重置图片加载状态、清除动画效果等
  }

  /**
   * 组件回收时调用，释放资源
   */
  aboutToRecycle() {
    // 释放大资源，如取消图片加载、关闭网络连接等
  }

  build() {
    Row() {
      Image(this.product.imageUrl)
        .width(80)
        .height(80)
        .borderRadius(10)
        .margin(10)
        .objectFit(ImageFit.Cover)
      
      Column({ space: 5 }) {
        Text(this.product.name)
          .fontSize(16)
          .fontWeight(FontWeight.Bold)
          .maxLines(2)
          .textOverflow({ overflow: TextOverflow.Ellipsis })
        
        Text(`¥${this.product.price}`)
          .fontSize(14)
          .fontColor('#FF5722')
      }
      .alignItems(HorizontalAlign.Start)
      .margin({ left: 10 })
      .layoutWeight(1)
    }
    .width('100%')
    .height(100)
    .backgroundColor('#FFF')
    .borderRadius(8)
    .margin({ bottom: 10 })
    .shadow({ radius: 2, color: '#1A000000', offsetX: 0, offsetY: 1 })
  }
}

// ProductListPage.ets
import { BasicDataSource, Product } from './BasicDataSource';
import { ProductListItem } from './ProductListItem';
import { promptAction } from '@kit.ArkUI';

@Entry
@Component
struct ProductListPage {
  private dataSource: BasicDataSource = new BasicDataSource(); @State isLoading: boolean = false; @State hasMore: boolean = true; private currentPage: number = 1; private isLoadingMore: boolean = false; // 防止重复加载 aboutToAppear() { this.loadInitialData(); } /** * 加载初始数据 */ async loadInitialData() { this.isLoading = true; try { const data = await this.requestData(1); this.dataSource.resetData(data); this.currentPage = 2; this.hasMore = data.length === 20; } catch (e) { promptAction.showToast({ message: '数据加载失败，请重试' }); } finally { this.isLoading = false; } } /** * 加载下一页数据 */ async loadMoreData() { if (this.isLoadingMore || !this.hasMore || this.isLoading) return; this.isLoadingMore = true; try { const data = await this.requestData(this.currentPage); this.dataSource.addData(data); this.currentPage += 1; this.hasMore = data.length === 20; } catch (e) { promptAction.showToast({ message: '加载更多失败' }); } finally { this.isLoadingMore = false; } } /** * 模拟网络请求数据 * @param page 页码 * @returns 商品列表数据 */ async requestData(page: number): Promise { // 实际项目中替换为真实API请求 return new Promise((resolve) => { setTimeout(() => { const products: Product[] = []; for (let i = 0; i < 20; i++) { const productId = `${page}-${i}`; products.push(new Product( productId, `商品 ${(page - 1) * 20 + i + 1}`, (Math.random() * 100).toFixed(2), 'https://example.com/product.jpg' // 替换为真实图片地址 )); } resolve(products); }, 800); }); } build() { Column() { // 顶部标题栏 Row() { Text('商品列表') .fontSize(18) .fontWeight(FontWeight.Bold) } .width('100%') .height(56) .backgroundColor('#FFF') .justifyContent(FlexAlign.Center) .shadow({ radius: 2, color: '#1A000000', offsetX: 0, offsetY: 1 }) // 列表区域 List({ space: 10 }) { // 下拉刷新组件 Refresh({ refreshing: this.isLoading }) .onRefresh(() => { this.loadInitialData(); }) // 懒加载列表 LazyForEach( this.dataSource, (item: Product, index: number) => { ListItem() { ProductListItem({ item: item }) } .onClick(() => { // 列表项点击事件 console.log(`点击商品: ${item.name}`); }) }, (item: Product) => item.id // 使用稳定唯一的业务ID作为Key ) // 加载更多状态提示 if (this.hasMore || this.isLoadingMore) { ListItem() { Row({ space: 8, justifyContent: FlexAlign.Center }) { if (this.isLoadingMore) { LoadingProgress() .width(20) .height(20) .color('#2b579a') } Text(this.isLoadingMore ? '加载中...' : '上拉加载更多') .fontSize(14) .fontColor('#999') } .height(50) } } else if (this.dataSource.totalCount() > 0) { ListItem() { Text('没有更多商品了') .fontSize(14) .fontColor('#999') .textAlign(TextAlign.Center) .height(50) } } } .cachedCount(3) // 预加载3屏数据，平衡流畅度与内存 .width('100%') .layoutWeight(1) .onScrollIndex((start: number, end: number) => { // 滚动到倒数第5项时触发加载更多 if (end >= this.dataSource.totalCount() - 5 && !this.isLoadingMore) { this.loadMoreData(); } }) .scrollBar(BarState.Auto) } .width('100%') .height('100%') .backgroundColor('#F5F5F5') } }

错误用法警示

❌ 禁止使用索引作为Key：数组增删时索引变化导致组件全部重建
❌ 禁止使用JSON序列化生成Key：性能开销大，内容变化时Key变化
❌ 禁止使用随机数作为Key：每次渲染Key都变化，完全丧失复用能力

// 多类型数据定义
interface FeedItem {
  id: string;
  type: 'text' | 'image' | 'video' | 'ad';
  content: any;
}

// 渲染逻辑
LazyForEach(this.feedDataSource, (item: FeedItem) => {
  ListItem() {
    switch (item.type) {
      case 'text':
        return TextFeedItem({ content: item.content })
      case 'image':
        return ImageFeedItem({ content: item.content })
      case 'video':
        return VideoFeedItem({ content: item.content })
      case 'ad':
        return AdFeedItem({ content: item.content })
      default:
        return EmptyView()
    }
  }
  .reuseId(`feed_${item.type}`) // 不同类型使用不同reuseId
}, (item: FeedItem) => item.id)

WaterFlow() {
  LazyForEach(this.dataSource, (item: Product) => {
    FlowItem() {
      ProductCard({ product: item })
    }
    .reuseId('product_card')
  })
}
.columnsTemplate('1fr 1fr') // 两列布局
.rowsGap(10)
.columnsGap(10)
.padding(10)
.cachedCount(3)
.width('100%')
.layoutWeight(1)

// 列表项删除方法
deleteItem(index: number) {
  animateTo({ duration: 300 }, () => {
    this.dataSource.deleteData(index);
  })
}

适用场景说明

LazyForEach适用于List、Grid、Swiper、WaterFlow等所有滚动容器。数据量小于100项时可使用ForEach，大于等于100项必须使用LazyForEach以保证性能。