懒加载LazyForEach是一种延迟加载的技术,它是在需要的时候才加载数据或资源,并在每次迭代过程中创建相应的组件,而不是一次性将所有内容都加载出来。懒加载通常应用于长列表、网格、瀑布流等数据量较大、子组件可重复使用的场景,当用户滚动页面到相应位置时,才会触发资源的加载,以减少组件的加载时间,提高应用性能,提升用户体验。
在声明式描述语句中,有两种方式控制列表、网格等容器类组件的渲染,分别为ForEach:循环渲染和LazyForEach:数据懒加载。
ForEach循环渲染的过程如下:
其数据加载、组件树挂载、页面渲染的示意图如下所示:

如果列表数据较少,数据一次性全量加载不是性能瓶颈时,可以直接使用ForEach;但是当数据量大、组件结构复杂的情况下ForEach会出现性能瓶颈。这是因为要一次性加载所有的列表数据,创建所有组件节点并完成组件树的构建,在数据量大时会非常耗时,从而导致页面启动时间过长。另外,屏幕可视区外的组件虽然不会显示在屏幕上,但是仍然会占用内存。在系统处于高负载的情况下,更容易出现性能问题,极限情况下甚至会导致应用异常退出。
LazyForEach懒加载的原理和渲染过程如下:
其数据加载、组件树挂载、页面渲染的示意图如下所示:

LazyForEach实现了按需加载,针对列表数据量大、列表组件复杂的场景,减少了页面首次启动时一次性加载数据的时间消耗,减少了内存峰值。不过在长列表滑动的过程中,因为需要根据用户的滑动行为不断地加载新的内容,这需要进行额外的数据请求和处理,会增加滑动时的计算量,从而对性能产生一定的影响。然而,合理使用LazyForEach的按需加载能力,通过在滑动停止或达到某个阈值时才进行加载,可以减少不必要的计算和请求,从而提高性能,给用户带来更好的体验。总之,在实现按需加载的场景中,需要综合考虑性能和用户体验的平衡,合理地优化加载逻辑和渲染方式,以提升整体的性能表现。
建议开发者优先使用Code Linter代码检查进行代码检查,重点关注@performance/hp-arkui-no-stringify-in-lazyforeach-key-generator规则。若扫描结果中出现该规则相关问题,可参考本章节提供的优化建议进行调整。
在使用LazyForEach时,我们需要分别实现数据源dataSource、键值生成函数keyGenerator、子组件生成函数itemGenerator。其中,数据源为IDataSource类型,需要开发者实现该接口。keyGenerator是一个函数,用于为每个item生成一个唯一且持久的键值以标识对应的组件,开发者可以通过它自定义键值的生成规则,关于键值生成规则,详情可参考键值生成规则。LazyForEach的itemGenerator函数会根据键值生成规则为数据源的每个数组项创建组件,组件的创建分为首次渲染和非首次渲染两种情况,详情可参考组件创建规则。
在使用LazyForEach进行组件复用时,键值生成函数keyGenerator中不推荐使用stringify。在复杂的业务场景中,使用stringify会对item对象进行序列化,最终把item转换成字符串,这过程需要消耗大量的时间和计算资源,从而导致页面性能降低。
长列表作为应用开发中最常见的开发场景之一,通常会包含成千上万个列表项,在此场景下,直接使用循环渲染ForEach一次性加载所有的列表项,会导致渲染时间过长,影响用户体验。而使用数据懒加载LazyForEach替换循环渲染ForEach,可以按需加载列表项,从而提升列表性能。数据懒加载的示例代码可以参考LazyForEach:数据懒加载。
虽然,按需加载列表项可以优化长列表性能,但在快速滑动长列表的场景下,可能会来不及加载需要显示的列表项,导致出现白块的现象,从而影响用户体验。而在ArkUI中,List、Grid、Swiper以及WaterFlow等容器组件提供了cachedCount属性,可以设置列表项的预加载数量,避免白块现象。
cachedCount可与以下数据渲染方式配合使用:
cachedCount的使用方法如下所示。
// Used in conjunction with LazyForEach
List() {
LazyForEach(this.data, (item: string) => {
ListItem() {
Text(item)
}
}, (item: string) => item)
}.cachedCount(3)
// Use in conjunction with Repeat
List() {
Repeat<string>(this.dataArr)
.each((ri: RepeatItem<string>) => {
ListItem() {
Text(ri.item)
}
})
}.cachedCount(3)
// Repeat is used in conjunction with the template-level cachedCount
List() {
Repeat<string>(this.dataArr)
.each((ri: RepeatItem<string>) => {
ListItem() {
Text(ri.item)
}
})
.template('A', (ri: RepeatItem<string>) => { // 'A' template
ListItem() {
Text('A_' + ri.item)
}
}, { cachedCount: 3 }) // The cache list capacity of the 'A' template is 3
}.cachedCount(3) 此外,HarmonyOS应用框架提供了组件复用能力,可以结合LazyForEach一起使用,进一步优化长列表的性能。组件复用会把组件树上将要移除的组件进行回收,回收的组件会进入到一个回收缓存区。后续创建新组件节点时,会复用缓存区中的节点,节约组件重新创建的时间。关于组件复用的详细原理可以参考自定义组件复用开发实践。针对长列表加载的性能优化,可以参考长列表加载丢帧优化。
瀑布流的内容呈现方式类似瀑布流一样,从上往下依次排列,每一列的高度不一定相同,整体呈现出瀑布流的视觉效果。在瀑布流中,经常使用LazyForEach实现数据按需加载,同时,结合onReachEnd、onScrollIndex方法实现无限瀑布流,关于瀑布流的优化详情可以参考优化瀑布流加载慢丢帧问题。
在混合布局中,容器内部包含不同的组件树。这种场景常见于电商首页、社交媒体等复杂应用,其中可能同时存在图片卡片、视频卡片、文本列表等多种异构组件类型。它们的渲染逻辑、数据结构和交互方式各不相同,对性能优化提出了更高要求。
1.针对多组件的快速滑动的场景,滑动过程中可能出现上一次渲染内容的“残影”问题。建议在自定义组件上标记@Reusable(参考:@ReusableV2装饰器:V2组件复用)以启用组件复用机制,同时需要在aboutToReuse生命周期回调中妥善处理组件状态的重置逻辑,确保组件在被复用时能够正确展示新数据。
2.针对不同类型的组件,建议为其分配不同的reuseId标识。当新数据需要渲染时,复用机制会优先在对应reuseId的缓存池中查找空闲组件实例。这样可以确保复用的组件与待渲染数据的类型相匹配,避免因组件结构不一致而触发不必要的销毁与重建流程,从而减少性能开销和潜在的界面卡顿。
3.针对白块问题,通过预加载机制,LazyForEach结合cachedCount属性一起使用,在渲染线程空闲时段提前构建和缓存即将进入视口的复杂嵌套组件实例,从而有效避免高速滚动场景下因组件创建耗时导致的视觉空白问题。
在LazyForEach的使用上,有一些限制条件和限制场景,详细的限制条件请参考使用限制,常见的限制场景总结如下:
当LazyForEach失效时,可能出现渲染错误、卡顿等现象,开发者可以使用日志、Profiler调优工具等方法来定位具体的问题。常见检查LazyForEach的失效方法有如下几种方式:
LazyForEach(this.data, (lazyForEachItem: string) => {
ListItem() {
Row() {
Text(lazyForEachItem).fontSize(50)
}.margin({ left: 10, right: 10 })
}.onAppear(() => {
// Record the number of times the component is created through onAppear
console.info('appear:' + lazyForEachItem);
})
}, (item: string) => {
// Print the key value in the keyGenerator function
console.info('key:' + item);
return item;
}) 
当父容器未设置明确的布局约束时,子容器会尝试计算并实例化所有列表项以完成自身的布局测量。在这种情况下,即使开发者使用了LazyForEach进行按需加载,系统仍会在瞬间创建数千个组件实例,导致懒加载机制完全失效。
场景:具备无限滚动能力的容器嵌套按需加载容器时,若未显式约束子容器的纵向布局空间,将使懒加载失效。
根因:父容器默认在主轴(垂直方向)提供无限的测绘空间,导致内部子容器无法界定视口边界。
结果:LazyForEach的按需实例化逻辑强依赖于视口裁剪,在无边界约束下,在单个布局帧内会瞬时实例化数据源中的数千个组件。导致懒加载机制瘫痪、严重的UI线程阻塞、内存瞬时溢出(OOM)以及首屏渲染耗时(TTI)的指数级增长。
解决方案:
给内部子容器设置明确的height()或使用百分比、layoutWeight(1)限制视口边界。
使用LazyVGridLayout作为WaterFlow或FlowItem的子组件,通过columnsTemplate和rowsGap、columnsGap等属性,来实现复杂嵌套布局,避免懒加载失效。
在LazyForEach的键值生成规则中,每个item对应着一个唯一且持久的键值,用于标识对应的组件。当不同的数据项有相同的键值时,框架可能找不到正确的数据项,导致子组件渲染错误。关于键值错误导致渲染错乱的案例,详情可以参考首次渲染中的示例。
当使用LazyForEach时,如果子组件ListItem过于复杂,在子组件创建时,将产生大量的布局计算耗时,最终导致该帧丢帧。关键代码如下所示。
@Entry
@Component
struct Index {
private data: MyDataSource = new MyDataSource();
aboutToAppear() {
for (let i = 0; i <= 30; i++) {
this.data.pushData(`Hello ${i}`)
}
}
build() {
List({ space: 3 }) {
LazyForEach(this.data, (lazyForEachItem: string) => {
ListItem() {
Column() {
ForEach(this.data.getAllData(), (forEachItem: string) => {
ListItem() {
Row() {
Text(lazyForEachItem + forEachItem).fontSize(50)
.onAppear(() => {
console.info("appear:" + lazyForEachItem)
})
}.margin({ left: 10, right: 10 })
}
}, (item: string) => item)
}
}
}, (item: string) => item)
}.cachedCount(5)
}
} 当Scroll容器嵌套List组件加载长列表时,若不指定List的宽高尺寸,则默认加载全部ListItem,导致按需加载失效,甚至会导致应用卡顿、崩溃,详细案例可参考布局优化指导。
当使用Grid容器时,如果GridItem没有设置高度,会加载所有子组件,设置了GridItem的宽高,会加载Grid显示区域内的子组件。参考案例代码如下:
@Entry
@Component
struct Index {
private data: MyDataSource = new MyDataSource();
private scroller: Scroller = new Scroller();
aboutToAppear() {
for (let i = 0; i <= 30; i++) {
this.data.pushData(`Hello ${i}`)
}
}
build() {
Column() {
Grid(this.scroller) {
LazyForEach(this.data, (lazyForEachItem: string) => {
GridItem() {
Text(lazyForEachItem)
.fontSize(50)
.width('100%')
}
.onAppear(() => {
console.info("appear:" + lazyForEachItem)
})
}, (item: string) => {
return item;
})
}
.columnsTemplate('1fr')
.enableScrollInteraction(true)
.width('100%')
.height(800)
.cachedCount(5)
}
.width('100%')
.height(700)
}
}