当前位置：首页 > news >正文

HarmonyOS7 虚拟列表不卡顿的关键在哪？动态高度和多列布局这样封装

news 2026/6/30 14:35:30

文章目录

- 前言
- LazyForEach 的局限在哪
- 动态高度：预估 + 缓存双保险
- 多列布局：Grid 结合虚拟滚动
- 头部吸附 Sticky Header
- 实战：通用 VirtualList 组件
- 下拉刷新的集成
- 用起来的感受

前言

用过 HarmonyOS 的LazyForEach都知道，它帮我们解决了大列表全量渲染的问题。但用久了你会发现，这东西在几个场景下力不从心：列表项高度不固定、要做多列瀑布流、还要搞头部吸附——光靠原生 API 根本搞不定。

这篇文章我把这几个坑全踩一遍，最后给你一个可以直接拿去用的VirtualList组件。

LazyForEach 的局限在哪

LazyForEach的核心思路是"滑到可视区才创建组件"，听着挺好。但它有个前提假设：每个列表项的高度是已知或固定的。

一旦你的列表项里混着单行文本、多行图文、甚至嵌套卡片，高度参差不齐，LazyForEach就懵了——它算不准滚动偏移量，会出现跳动、白屏、定位错乱。

再加上它不支持多列布局，你想做个类似小红书的瀑布流，得自己另起炉灶。

动态高度：预估 + 缓存双保险

我的方案是"先估后测"。给每种类型的数据项一个预估高度，渲染完成后再用onAreaChange回调拿到真实高度，存进缓存。

// 高度缓存管理器classHeightCache{privatecache:Map<string,number>=newMap()privatedefaultHeight:numberconstructor(defaultHeight:number=80){this.defaultHeight=defaultHeight}getHeight(key:string):number{returnthis.cache.get(key)??this.defaultHeight}setHeight(key:string,height:number):void{this.cache.set(key,height)}// 计算指定范围内的累计高度getTotalHeight(startIndex:number,endIndex:number,keyGetter:(index:number)=>string):number{lettotal=0for(leti=startIndex;i<endIndex;i++){total+=this.getHeight(keyGetter(i))}returntotal}}

关键点在于：预估高度让滚动条一开始就有正确的比例，真实高度缓存让后续滚动越来越精准。跑通这个逻辑后，列表跳动的问题基本消失了。

多列布局：Grid 结合虚拟滚动

HarmonyOS 的WaterFlow组件本身支持虚拟滚动，但在自定义程度上有很多限制。我选择用Grid+ 手动可视区计算来实现。

思路是把数据按列数分组，每列独立维护一个高度累加器，新数据总是丢给当前最短的那列：

functiondistributeToColumns<T>(items:T[],columnCount:number,heightCache:HeightCache):T[][]{constcolumns:T[][]=Array.from({length:columnCount},()=>[])constcolumnHeights:number[]=newArray(columnCount).fill(0)for(constitemofitems){// 找最短列constminIndex=columnHeights.indexOf(Math.min(...columnHeights))columns[minIndex].push(item)columnHeights[minIndex]+=heightCache.getHeight((itemasany).id)}returncolumns}

这样做瀑布流布局，每列的高度差异最小化，视觉上更协调。

头部吸附 Sticky Header

Sticky Header 的实现核心是监听滚动偏移量。当某个 section 的 header 滚出可视区顶部时，用一个Stack在顶部叠一层"吸住"的 header。

@StatestickyHeaderIndex:number=0@StatestickyOffset:number=0// 在 onScroll 回调里计算onScroll((scrollOffset:number)=>{// 遍历 section 的累计高度，找到当前应该吸附的 sectionletaccumulated=0for(leti=0;i<this.sections.length;i++){constsectionTop=accumulatedconstsectionBottom=accumulated+this.heightCache.getHeight(`section-${i}`)if(scrollOffset>=sectionTop&&scrollOffset<sectionBottom){this.stickyHeaderIndex=i// 当下一段 header 要顶上来时，当前吸附 header 要往上推this.stickyOffset=Math.max(0,scrollOffset-sectionTop)break}accumulated=sectionBottom}})

这个stickyOffset很关键——它让吸附的 header 在被下一个 header 推走时有个自然的过渡效果，不会突然消失。

实战：通用 VirtualList 组件

把这些能力拼到一起，封装成一个通用组件。对外暴露数据源、列数、header 构建器、item 构建器：

@Componentexportstruct VirtualList<T>{@Propitems:T[]=[]@PropcolumnCount:number=1@PropestimatedItemHeight:number=80@BuilderParamitemBuilder:(item:T,index:number)=>void@BuilderParamsectionHeaderBuilder?:(sectionIndex:number)=>void@PropenableStickyHeader:boolean=false@PropenablePullRefresh:boolean=true@EventonRefresh?:()=>voidprivateheightCache:HeightCache=newHeightCache()@StateprivatestickyHeaderIndex:number=0@StateprivatestickyOffset:number=0@StateprivateisRefreshing:boolean=falsebuild(){Stack(){Scroll(){Column(){ForEach(this.sections,(section:T[],sectionIdx:number)=>{// Section Headerif(this.sectionHeaderBuilder){Column(){this.sectionHeaderBuilder(sectionIdx)}.onAreaChange((_old:Area,newArea:Area)=>{this.heightCache.setHeight(`section-${sectionIdx}`,newArea.heightasnumber)})}// 多列布局Row(){ForEach(distributeToColumns(section,this.columnCount,this.heightCache),(column:T[],colIdx:number)=>{Column(){ForEach(column,(item:T,itemIdx:number)=>{Column(){this.itemBuilder(item,itemIdx)}.onAreaChange((_old:Area,newArea:Area)=>{this.heightCache.setHeight((itemasany).id,newArea.heightasnumber)})})}.layoutWeight(1)})}})}}.onScroll((offset:number)=>{if(this.enableStickyHeader){this.updateStickyHeader(offset)}})// Sticky Header 覆盖层if(this.enableStickyHeader&&this.sectionHeaderBuilder){Column(){this.sectionHeaderBuilder(this.stickyHeaderIndex)}.translate({y:-this.stickyOffset}).position({top:0}).width('100%').zIndex(10)}}}privateupdateStickyHeader(scrollOffset:number):void{// 同上面 Sticky Header 的计算逻辑}}

下拉刷新的集成

下拉刷新直接在Scroll外面包一层Refresh组件就行，但要注意跟 Sticky Header 的层级关系：

Refresh({refreshing:this.isRefreshing}){// 上面的 Scroll 内容}.onRefreshing(()=>{this.onRefresh?.()// 数据加载完后关闭刷新状态setTimeout(()=>{this.isRefreshing=false},1000)})