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

HarmonyOS7 列表流实战-----分组列表吸顶原来就这几步

news 2026/6/25 16:53:04

文章目录

- - 源码获取
  - 吸顶这件事，难点不在动画，而在分组
  - 真正的前提不是 `sticky`，而是 `ListItemGroup`
  - 标题头为什么最好单独抽出来
  - 真正让标题吸住顶部的，就这一行
  - 如果只看一个页面来练，我更推荐 `CityList`
  - 你自己复刻时，最少得满足这三个条件
  - 有个细节很多人真会省，但我建议别省
  - 这种结构以后能直接套到哪类页面
  - 我最想提醒小白的三个误区
  - - 误区一: 以为吸顶一定要自己算滚动距离
    - 误区二: 把标题直接塞进 `ListItem`
    - 误区三: 标题区样式写得太敷衍
  - 给你一个非常适合练手的小作业
  - 最后一句

源码获取

如果你想一边对照文章一边实操，建议直接把示例工程拉到本地。项目 Git 地址：https://gitcode.com/HarmonyOS_Samples/CommonListFlows。

第一次看到“分组标题吸顶”的页面，很多人会本能地觉得这玩意儿很高级。

然后脑子里立刻开始脑补: 要不要监听滚动距离，要不要自己算偏移，要不要动态改定位。结果还没写代码，人已经先把自己吓着了。

说实话，这种担心大多是想多了。

在 ArkUI 的List体系里，分组吸顶真正关键的不是你会不会手搓动画，而是你有没有把列表结构组织对。这个项目里的HomePage和CityList，刚好把这件事讲得很明白。

吸顶这件事，难点不在动画，而在分组

先把概念掰直。

所谓分组吸顶，就是你往下滑的时候，当前分组标题固定在顶部，等下一个分组上来，再把它顶走。

这种交互非常常见:

城市选择页
通讯录
分类商品列表
按日期分组的消息页

所以你现在学的不是一个花哨技巧，而是一类特别高频的页面基础能力。

真正的前提不是`sticky`，而是`ListItemGroup`

先看HomePage里景区分组的写法:

ForEach(this.scenicSpotTitle,(item:Resource)=>{ListItemGroup({header:this.scenicSpotHeader(item)}){ForEach(this.scenicSpotArray,(scenicSpotItem:Resource)=>{ListItem(){this.scenicSpotDetailBuilder(scenicSpotItem)}},(scenicSpotItem:Resource)=>JSON.stringify(scenicSpotItem))}},(item:Resource)=>JSON.stringify(item))

这段代码最值得记住的不是遍历细节，而是结构关系:

外层按分类分组
每一组都用ListItemGroup
组里面再放具体ListItem

这一步才是吸顶真正的地基。

因为框架只有先知道“这是一组内容，这是一组的头部”，后面才有可能帮你做吸顶。你如果连分组关系都没建立，光盯着吸顶效果本身，基本是在白忙活。

标题头为什么最好单独抽出来

项目把分组头专门写成了一个Builder:

@BuilderscenicSpotHeader(title:Resource){Column(){Text(title).width('100%').height(50).fontSize(18).fontWeight(FontWeight.Bold).backgroundColor(0xF1F3F5)}}

这一步很实用。

因为分组标题通常不是只出现一次。你今天想改高度，明天想改背景色，后天又想加图标或者间距，如果一开始就散落在各处，后面会改得很烦。

抽出来以后，结构更清楚，维护也轻松。

真正让标题吸住顶部的，就这一行

很多人以为要写很长的滚动逻辑，其实项目里真正生效的是这句:

.sticky(StickyStyle.Header)

它直接挂在List上:

List({space:12}){// 列表内容}.sticky(StickyStyle.Header)

说白了，ArkUI 已经把常见分组吸顶能力准备好了。你要做的不是重新发明一遍，而是把它需要的结构喂对。

所以这里的正确心态应该是:

先把分组关系建好
再把分组头定义清楚
最后让List开启sticky

顺序别反。

如果只看一个页面来练，我更推荐`CityList`

HomePage里的分组吸顶是入门版，CityList则更像标准模板。

它的核心结构是这样的:

List({scroller:this.cityScroller}){ListItemGroup({header:this.itemHead($r('app.string.current_city'))}){ListItem(){Text(this.currentCity)}}ListItemGroup({header:this.itemHead($r('app.string.popular_cities'))}){ForEach(this.hotCities,(item:string)=>{ListItem(){this.textContent(item)}})}ForEach(this.groupWorldList,(item:string)=>{ListItemGroup({header:this.itemHead(item)}){ForEach(this.getCitiesWithGroupName(item),(cityItem:City)=>{ListItem(){this.textContent(cityItem.city)}})}})}.sticky(StickyStyle.Header)