企业官网建设流程全解析

前阵子有个开发群里的朋友问我，说他在项目里把ForEach换成LazyForEach之后，列表倒是流畅了不少，但是偶尔会出现数据对不上的情况，改了一条数据，界面上有时候刷新有时候不刷新，搞得一头雾水。这个问题其实问到了点子上，LazyForEach在鸿蒙的 ArkTS 开发里算是个老朋友了，但真正能把它用明白、用透的开发者，还真不算多。绝大多数人只是知道它能懒加载提升性能，但对它的键值生成规则、缓存复用机制这些核心原理，往往是一知半解。这篇文章我就以Arkts语法＜LazyForEach＞为主题，把自己在项目里使用这个组件的经验、踩过的坑还有总结出来的实操方法，一次性整理出来，希望能帮到正在折腾鸿蒙列表开发的你。

1. LazyForEach 到底是什么，为什么大家都在用

1.1 从一个最头疼的场景说起

做鸿蒙应用开发，不管是做商城、资讯App还是聊天工具，都绕不开一个场景：长列表。数据动不动就是几百上千条，甚至上万条。如果你一开始用的是ForEach，也就是一次性把所有列表项全部渲染出来，那性能问题真的非常明显。我实测过一个大概有两千条数据的简单文本列表，用ForEach渲染，首帧耗时基本都在一秒以上，滑动的时候帧率波动也很厉害，掉到三四十帧是常事，体感就是卡顿、掉帧、白屏时间长。

为什么ForEach会这么吃力？因为它的逻辑很简单粗暴：你给我多少数据，我一次性全部创建对应的组件节点，全塞进组件树里。数据量小的时候还好，一旦上千，光是创建这些节点、计算布局、渲染上屏，就已经把主线程的活儿干满了。而且，这些节点会一直挂在树里，即使你没滑到屏幕外的地方，组件依然存在，内存也会一路飙升。

LazyForEach解决的就是这个痛点。翻译成大白话，它叫“懒加载循环渲染”，核心思想是：我只创建当前视口内（以及视口附近缓存区）需要的组件，滑出去的我回收，滑进来的我再创建。实现的效果就是，不管底层数据是一千条还是一万条，界面上同时存在的组件节点数量基本是稳定的，首帧耗时也能控制在几百毫秒甚至更低。

1.2 和 ForEach 的对比，差别真的很大

很多人刚接触LazyForEach的时候，有个误区，觉得它就是把ForEach换个名字，参数长得差不多，于是直接替换了事。其实两者在底层机制上的差距非常大，我整理了一个对比表，方便你一眼看明白：

那个群友遇到的问题，本质上就是替换之后没有处理好键值生成规则，导致LazyForEach在数据更新时无法精确匹配到对应的组件，从而出现各种“灵异事件”。所以，在你决定用LazyForEach之前，我建议你先停下来想清楚：你的列表数据量大不大？列表项是否需要频繁刷新？如果你的数据不到二十条，而且基本不变化，那么ForEach完全够用，不必为了用而用。如果你的数据超过几十条，或者列表项的复杂度比较高（图片、多行文本、交互按钮），那么LazyForEach就是你的首选。

2. 上手第一步：LazyForEach 基础用法与数据源规范

2.1 从一个最小可用的例子开始

先不扯太多理论，我直接给你一个最基础的LazyForEach用法示例。在 ArkUI 里，LazyForEach的完整参数是三个：

LazyForEach( dataSource: IDataSource, // 数据源，需要实现特定接口 itemGenerator: (item: any, index?: number) => void, // 生成列表项组件 keyGenerator?: (item: any, index?: number) => string // 键值生成函数 )

一个最简单、能跑起来的例子长这样：

// 1. 定义一个简单的数据类型 class SimpleItem { id: number; name: string; constructor(id: number, name: string) { this.id = id; this.name = name; } } // 2. 在自定义组件里使用 LazyForEach @Component export struct SimpleList { private dataSource: MyDataSource = new MyDataSource(); build() { List() { LazyForEach(this.dataSource, (item: SimpleItem) => { ListItem() { Text(item.name) .fontSize(16) .padding(12) } }, (item: SimpleItem) => item.id.toString()) } .width('100%') .height('100%') } }

但注意，MyDataSource是不能随便搞一个普通类糊弄过去的。LazyForEach对数据源有硬性要求：必须实现IDataSource接口，否则组件根本不知道你有多少条数据、数据在哪里、该怎么通知它更新。换句话说，LazyForEach不接收数组，它接收的是一个符合规范的数据源对象。

2.2 IDataSource 接口你到底要重写哪些方法

IDataSource接口总共包含四个必须实现的方法，每个方法都有它的用途：

一个教科书式的数据源实现是这样写的：

class MyDataSource implements IDataSource { private dataList: SimpleItem[] = []; private listeners: DataChangeListener[] = []; constructor(dataList: SimpleItem[]) { this.dataList = dataList; } totalCount(): number { return this.dataList.length; } getData(index: number): any { return this.dataList[index]; } registerDataChangeListener(listener: DataChangeListener): void { if (this.listeners.indexOf(listener) < 0) { this.listeners.push(listener); } } unregisterDataChangeListener(listener: DataChangeListener): void { const index = this.listeners.indexOf(listener); if (index >= 0) { this.listeners.splice(index, 1); } } // 这个方法是我自己加的，方便外部添加数据时通知界面刷新 addData(item: SimpleItem): void { this.dataList.push(item); this.listeners.forEach(listener => { listener.onDataAdded(this.dataList.length - 1); }); } // 同理，更新某一条数据时调用 updateData(index: number, newItem: SimpleItem): void { this.dataList[index] = newItem; this.listeners.forEach(listener => { listener.onDataChanged(index); }); } }

你可能会觉得，一个简单的数组传进去不就行了吗，为什么要搞得这么麻烦？实际上这个接口设计背后是有道理的：它把“数据存储”和“数据变更通知”剥离开，让LazyForEach可以精准地知道哪一条数据发生了变化，从而只更新对应的那一个组件，而不是像ForEach那样动不动就全量重建。这也是LazyForEach性能优势的一个重要来源。

3. 键值生成规则，LazyForEach 的灵魂

3.1 键值到底是什么，为什么它这么关键

如果你只用过ForEach，并且经常用默认的键值规则（也就是用数据项的索引 index 做 key），那你可能没意识到键值在LazyForEach里的分量有多重。说它是灵魂，一点都不夸张。

LazyForEach在内部维护了一个“键值-组件”的映射关系。每个列表项组件都有一个唯一key，框架通过这个key来判断：当前需要渲染的数据项之前有没有对应的组件？如果有，直接复用；如果没有，新建一个；如果某个key对应的组件已经滑出屏幕且超出缓存范围，就销毁。这套机制的顺畅程度，完全取决于key的稳定性。如果一个对象对应的key发生了变化，LazyForEach会认为这是一个全新的数据项，会销毁旧组件、创建新组件，频繁出现这种情况，性能会大打折扣，甚至出现闪烁或者错乱。

举一个生活化的类比：假设你是快递分拣员，每个包裹上贴着一张标签（key），你只需要看一眼标签就知道这个包裹属于哪一片区域。但如果标签经常贴错或者模糊，你就得拆开包裹确认，效率自然就低了。

3.2 三种键值生成方式，用不对就等着踩坑

实际开发中，键值生成函数有三种常见写法：

第一种，用数据项的唯一ID：

(item: SimpleItem) => item.id.toString()

这是我最推荐的写法，前提是你的数据项里确实有唯一ID（自增主键、UUID、组合ID都行）。ID稳定不变，键值就稳定，组件复用效率最高。

第二种，用多个字段拼接：

(item: CommentItem) => `${item.userId}_${item.timestamp}`

这种适合没有显式ID，但可以通过多个字段组合出唯一标识的场景。比如评论列表里，同一个用户可能发多条评论，单纯用userId会冲突，加上时间戳就唯一了。

第三种，用索引 index：

(item: SimpleItem, index: number) => index.toString()

这种是我见过踩坑最多的。用index做key在ForEach里可能还勉强能跑，但在LazyForEach里隐患非常大。因为index是位置属性，不是对象属性。当你在列表头部插入一条新数据时，所有后续元素的index都会变，它们的key也就全变了。LazyForEach会认为整条列表都“更新”了，最终表现就是你看到的一大片重渲染，甚至组件复用时传入的还是旧数据，界面和数据对不上。

3.3 key 生成时容易忽略的三个细节

除了不用index当key，还有几个细节容易被忽略：

一是键值必须是字符串类型。如果你传了数字进去，虽然有些版本框架会自动转成字符串，但最好还是显式调用toString()，避免不同版本之间的行为差异。

二是键值必须稳定且唯一。同一个数据项在每次调用键值生成函数时，返回值要一致；不同数据项的键值不能重复。键值一旦冲突，LazyForEach可能直接报错，或者表现异常——明明有十条数据，界面上只出现了九条，另一条不知道跑哪去了。

三是键值函数不要做复杂计算。键值生成函数在数据更新、滑动过程中会被高频调用，如果在里面写耗时的逻辑，比如拼接大字符串、做正则匹配，性能影响会直接反映在滑动流畅度上。保持简单，最好就是返回一个字符串属性或者几个字段的简单拼接。

4. 缓存复用机制，把它搞懂才算真正会用

4.1 组件复用到底是怎么发生的

LazyForEach能带来性能提升，除了“按需创建”，还有一个关键机制是“缓存复用”。当某个列表项滑出视口时，框架不会立刻销毁它，而是把它放进一个缓存池。当滚动方向反向，或者附近有新的数据项需要上屏时，如果缓存池里有相同key的组件，就直接拿出来用，省掉重新创建组件的时间和开销。

这个机制听起来很美好，但有个地方需要特别注意：缓存复用不只是组件层面的复用，更是状态层面的保留。如果你在列表项里使用了@State装饰的变量，或者表单项里有用户输入的内容，那么组件被缓存再复用时，这些状态是保留的。这带来一个很经典的坑：列表项复用时，老状态没清干净，导致显示错乱。

我举一个实际例子。我做过一个任务清单页面，每个列表项里有个复选框，用户勾选后@State isChecked变为true，同时数据源里的字段也相应更新。一开始我在列表项的onAppear里根据数据初始化状态，结果滑出去再滑回来，复选框状态经常不对——有的该勾的没勾，有的不该勾的却勾上了。原因就是组件被复用时，@State还是旧值，而我没有在数据更新或组件复用时重新赋值。解决办法是在列表项的build()里，用数据源的值去驱动UI状态，而不是让UI状态自己“记忆”。简单说，数据是唯一的真相源，UI尽量别存需要跨复用周期的状态。

4.2 cachedCount 参数，怎么设置才合适

LazyForEach支持通过cachedCount属性设置缓存数量：

List() { LazyForEach(this.dataSource, (item: ItemType) => { ListItem() { // ... } }, (item: ItemType) => item.id.toString()) } .cachedCount(5)

注意，cachedCount是加在List上的，不是加在LazyForEach上的。它表示在视口之外，上下各额外保留多少个列表项组件不销毁。比如你的屏幕一屏能显示10条数据，cachedCount(5)就意味着上下各多缓存5条，实际渲染的组件数最多约20条。

这个参数不是越大越好。调大缓存，好处是滑动时更不容易出现白屏和闪烁，因为在滑到下一个数据项之前它已经被提前渲染好了；坏处是组件数量和内存占用会上升。我一般建议根据列表项的复杂度和滚动速度来调：如果列表项里有网络图片，图片加载比较慢，那就适当调大一点，比如5到10；如果列表项很轻量（纯文本），2到5就够了。如果滑动深度很深、速度很快，比如通讯录那种快速滚动，可以再往上加。

4.3 静态和动态两种模式，别搞混了

LazyForEach还有一个容易忽略的差异：如果数据源在创建之后完全不会变化，那么可以不调用registerDataChangeListener里的通知方法，框架会把列表当成静态数据来处理；如果数据源会增删改，那就必须在每次操作后调用对应的DataChangeListener方法。

很多人写数据源的时候，图省事，数据变了只调一个onDataReloaded()，这个方法是“全量刷新”的意思，它会清空所有的缓存并按当前数据整体重建列表项。结果就是每次只改了一条数据，整个列表都抖一下，性能甚至比ForEach还差。正确的做法是：新增用onDataAdded(index)，删除用onDataDeleted(index)，移动用onDataMoved(from, to)，修改用onDataChanged(index)，只有数据源整体被替换（比如从本地缓存加载了一大批新数据）时才用onDataReloaded()。

5. 实操：一个长列表场景的完整实现与性能调优

5.1 定义一个健壮的数据源

前面讲了那么多理论，现在我把一个相对完整的实战项目拆给你看。假设我们要做一个资讯类的首页信息流，每条资讯包含标题、封面图URL、发布时间、阅读量这几个字段。因为数据会做分页懒加载，所以需要一个既能支持追加又能支持下拉刷新的数据源。

class NewsItem { id: number; // 唯一标识 title: string; // 标题 coverUrl: string; // 封面图 publishTime: string; // 发布时间 readCount: number; // 阅读量 // ...构造函数略 } class NewsDataSource implements IDataSource { private newsList: NewsItem[] = []; private listeners: DataChangeListener[] = []; totalCount(): number { return this.newsList.length; } getData(index: number): any { return this.newsList[index]; } registerDataChangeListener(listener: DataChangeListener): void { if (this.listeners.indexOf(listener) < 0) { this.listeners.push(listener); } } unregisterDataChangeListener(listener: DataChangeListener): void { const idx = this.listeners.indexOf(listener); if (idx >= 0) { this.listeners.splice(idx, 1); } } // 首屏/下拉刷新：整个数据源替换 reloadData(items: NewsItem[]): void { this.newsList = items; this.listeners.forEach(listener => { listener.onDataReloaded(); }); } // 分页追加：在末尾新增若干条 addItems(items: NewsItem[]): void { const startIndex = this.newsList.length; this.newsList = this.newsList.concat(items); this.listeners.forEach(listener => { for (let i = 0; i < items.length; i++) { listener.onDataAdded(startIndex + i); } }); } // 单条更新：比如修改某条资讯的阅读量 updateItem(index: number, updatedItem: NewsItem): void { this.newsList[index] = updatedItem; this.listeners.forEach(listener => { listener.onDataChanged(index); }); } }

这里有一个我踩过坑后总结出来的细节：追加数据时，onDataAdded要逐条调用，传入的是每一条新增数据对应的真实索引。有些开发者图方便，追加数据后只调用一次onDataAdded(0)，这会让LazyForEach以为是在索引0的位置插入了一条数据，结果后面的数据全部乱套，UI和数据错位得让人崩溃。

5.2 列表页面的搭建与性能参数设置

有了数据源，接下来就是搭建列表页。信息流页面一般包含大图卡片、视频卡片、纯文本卡片不同类型，这里我先用最简单的大图卡片举例。你可以根据实际项目需求扩展卡片类型，注意给不同的卡片类型分配不同的组件结构就好了。

@Entry @Component struct NewsFeedPage { @State dataSource: NewsDataSource = new NewsDataSource(); private pageIndex: number = 1; aboutToAppear(): void { // 模拟首屏加载数据 this.loadMoreData(); } loadMoreData(): void { // 模拟网络请求返回新数据 const newItems: NewsItem[] = []; for (let i = 0; i < 20; i++) { newItems.push(new NewsItem( this.pageIndex * 100 + i, `资讯标题 ${this.pageIndex}-${i}`, 'https://example.com/cover.png', '2024-01-01 10:00', 1000 + i )); } this.pageIndex++; this.dataSource.addItems(newItems); } build() { Column() { List() { LazyForEach(this.dataSource, (item: NewsItem, index: number) => { ListItem() { this.itemCard(item) } .onAppear(() => { // 触底加载：当最后一个列表项即将进入视口时，加载下一页 if (index === this.dataSource.totalCount() - 1) { this.loadMoreData(); } }) }, (item: NewsItem) => item.id.toString()) } .width('100%') .height('100%') .cachedCount(5) .scrollBar(BarState.Off) .edgeEffect(EdgeEffect.Spring) } } @Builder itemCard(item: NewsItem) { Row() { Image(item.coverUrl) .width(80) .height(80) .borderRadius(8) .objectFit(ImageFit.Cover) Column() { Text(item.title) .fontSize(16) .fontWeight(FontWeight.Medium) .maxLines(2) .textOverflow({ overflow: TextOverflow.Ellipsis }) Text(`${item.readCount} 阅读`) .fontSize(12) .fontColor('#999999') .margin({ top: 8 }) } .alignItems(HorizontalAlign.Start) .layoutWeight(1) .margin({ left: 12 }) } .padding(12) .width('100%') .backgroundColor('#FFFFFF') .borderRadius(12) .margin({ bottom: 8 }) } }

这段代码里有几个细节值得展开讲。

第一个是cachedCount(5)的选择。资讯卡片里有网络图片，图片解码需要时间，缓存太小的话快速滑动时会出现图片区域空白闪烁，5是我在多个机型上实测下来比较稳妥的值。如果你是做重度图片场景（比如瀑布流），我会建议cachedCount提高到8到10。当然，所有参数都建议用真机调试后再定，我给的只是起点。

第二个是触底加载的写法。我用了onAppear判断当前索引是否等于总条数减一，这样当最后一条进入视口时就开始加载下一页。这种写法简单，但有一个缺点：如果手势停在最后一条上反复上下滑动，可能触发多次加载。更稳的方案是用onReachEnd，它是专门用来触发触底加载的：

List() { // ... } .onReachEnd(() => { // 触底加载下一页 this.loadMoreData(); })

第三种是下拉刷新。List组件本身支持onRefresh以及Refresh容器组件，可以配合onRefresh回调做下拉刷新动作。刷新的核心是调用reloadData，但要注意先清空旧列表再更新，否则onDataReloaded会结合现有数据源重新铺列表。

5.3 性能调优：我实际测试后的对比数据

在整个项目开发完以后，我做了一组简单的对比测试。测试手机是某主流中端机型，数据量是1000条纯文本资讯标题。分别使用ForEach和LazyForEach跑同样场景：

当然，这是极端测试场景下的对比数据，不同机型、不同列表项复制度会有偏差，但趋势是明确的：数据量越大，列表项越复杂，LazyForEach的优势就越明显。如果你的列表只有十几条数据还非要上LazyForEach，那这种优势体现不出来，反而因为键值管理多了一层开销，甚至可能不如直接用ForEach来得轻快。所以选型的时候一定要结合实际场景。

6. 常见问题与排查技巧实录

6.1 数据改了，列表却不刷新

这是LazyForEach使用中最常见的问题，没有之一。表现是：你在数据源里修改了某个对象，调用了onDataChanged(index)，但界面上对应列项完全没有变化，或者过一会儿才动一下。

我的排查思路首先是确认 index 是否对应正确的数据项。如果 index 传错了，比如把旧列表的位置当成新列表的位置，刷新自然就不对。其次是确认修改的是不是同一个对象引用。LazyForEach的组件复用依赖键值，如果你修改了对象的 ID 字段，键值变了，框架会把它当作新数据，旧位置就不会刷新。这种情况下你应该保留 ID 不变，只改其他内容字段。

另外，还有一个隐藏的坑：如果你在getData方法里每次都返回新对象，而不是返回缓存的同一个对象引用，那么即使调用了onDataChanged，组件拿到了一个全新对象，状态又有可能和上一次对不上。数据源的getData应该保持稳定的引用返回，而不是每次新建。

6.2 滑动变卡，帧率上不去

滑动卡顿的原因比较多。首先排查列表项组件是不是太重，比如每个ListItem里嵌了多层Column/Row、大量阴影效果、模糊效果，这些都会在复用和布局时产生额外开销。可以用@Builder抽离公共布局，减少嵌套层级，去掉非必要的视觉效果。

其次，如果列表项里有图片，一定要设置固定的宽高，千万别让图片在加载前后撑大或缩小列表项，否则会引起布局抖动和滚动性能恶化。图片库也建议开启内存缓存和复用，否则网络图片频繁加载同样会卡。

最后，如果以上都优化了还是卡，可以尝试把List换成WaterFlow或者Grid，因为不同容器的布局引擎对错落布局的渲染优化程度不一样。有些场景下换一个容器，滑动性能反而会有惊喜。

6.3 键值冲突导致的数据错乱

还有一种问题发生在数据源内部：两个数据项的键值一样了。比如用户昵称加时间戳生成的key，两个用户同一秒发了评论，key就冲突了。表现是列表偶尔会少显示一条数据，或者两条数据共用同一个组件，显示内容一会儿是A的一会儿是B的。

排查方式是在键值生成函数里临时加日志，把所有生成的key打出来，看看有没有重复。解决方式很简单：key的生成带上数据源的唯一字段，或者干脆用一个自己维护的自增序列作为key。记住，key的职责只有一个：唯一标识一个数据项，不需要有其他含义。

6.4 常见问题速查表

7. 一点个人体会，以及扩展思路

项目里用了这么久的LazyForEach，我最大的体会是：它确实强大，但强大的前提是你必须理解它的两个底层机制——键值匹配和缓存复用。很多人觉得它是“性能神器”，只要用了就能解决一切卡顿问题，这很明显是个误区。你如果只是替换组件名而不去设计好数据源、键值生成和缓存策略，那效果不但没有提升，反而可能出现一系列莫名其妙的问题。

另外我也想给读者一个扩展思路：LazyForEach不只可以用在List里，在Grid和WaterFlow等容器里同样适用，处理瀑布流图片墙、宫格商品列表的时候，思路是完全一样的。你可以把这次总结出来的数据源设计方法和键值规则迁移过去，学习成本几乎为零。如果后续有机会，我会再单独写一篇关于瀑布流场景下LazyForEach配合图片懒加载踩坑经验的内容，那个场景里的问题会更刁钻一点。

最后再分享一个小技巧：调试LazyForEach相关的问题时，建议在数据源的所有数据变更通知方法里都加上日志输出。一旦UI表现异常，你一眼就能看出当前到底触发的是onDataChanged还是onDataReloaded，dataIndex又是从哪传出来的。这个习惯帮我节省了非常多排查时间，真心推荐你也试试。