StickyTimeLine快速上手：如何5分钟搭出吸顶时间轴（附Kotlin与Java示例代码）

StickyTimeLine快速上手：如何5分钟搭出吸顶时间轴（附Kotlin与Java示例代码）

【免费下载链接】StickyTimeLine:book:StickyTimeLine is timeline view for android.项目地址: https://gitcode.com/gh_mirrors/st/StickyTimeLine

StickyTimeLine 是一款专为 Android 打造的吸顶时间轴（Sticky TimeLine）开源库，让分组标题在滚动时自动吸附在屏幕顶部。它同时支持传统 View 系统和 Jetpack Compose 两套技术栈，只需一行 Gradle 依赖、几行回调代码，5 分钟即可在应用里搭出带"时间线 + 圆点 + 吸顶分组头"的漂亮列表，非常适合做音乐专辑年表、股票行情流水、历史事件时间线等场景。

一分钟认识 StickyTimeLine：它解决了什么问题？

想象一个按年份分组的历史列表：滚动时，"2025 年"这个分组标题会钉在列表顶部不动，直到下一组标题顶上来才切换——这就是"吸顶（Sticky）"效果。

自己实现这个效果，通常需要处理复杂的偏移计算和 ItemDecoration 绘制，而 StickyTimeLine 把这些全部封装好了：

• 📌吸顶分组标题：分组头自动置顶，切换平滑
• 📈时间轴 + 圆点：内置竖线、圆点、描边，还支持自定义 Drawable 圆点
• 🔄双向支持：View 系统的TimeLineRecyclerView和 Compose 的StickyTimeLineLazyColumn/StickyTimeLineLazyRow
• 🎨高度可定制：线条颜色、粗细、圆点半径、分组背景色等 10 余个属性随意调
• 🚀零性能负担：基于 RecyclerView 复用机制和 Compose 懒加载实现，长列表也流畅

快速上手：3 步搭出你的第一条时间轴

第 1 步：引入 Gradle 依赖

根据你的技术栈二选一（版本以 Maven Central 最新为准）：

// View 系统 implementation 'io.github.sangcomz:StickyTimeLine:x.x.x' // Jetpack Compose implementation 'io.github.sangcomz:stickytimeline-compose:x.x.x'

💡 提示：想直接运行完整 Demo 学习？可以git clone本仓库后打开 Android Studio，app模块是 View 版示例，sample-compose模块是 Compose 版示例。

第 2 步：在布局中加入时间轴组件

View 系统中，只需在 XML 里声明一个TimeLineRecyclerView（它继承自 RecyclerView，核心逻辑见 TimeLineRecyclerView.kt）：

<xyz.sangcomz.stickytimelineview.TimeLineRecyclerView android:id="@+id/recycler_view" android:layout_width="match_parent" android:layout_height="wrap_content" />

第 3 步：实现 SectionCallback 并交给组件

告诉库"哪些位置是新分组、分组头显示什么"。接口定义在 SectionCallback.kt，只有两个方法：

recyclerView.addItemDecoration(object : SectionCallback { // 当前项与前一项的分组键不同，即视为新分组的开头 override fun isSection(position: Int) = singerList[position].debuted != singerList[position - 1].debuted // 返回分组头的标题与副标题 override fun getSectionHeader(position: Int): SectionInfo? = SectionInfo(singerList[position].debuted, singerList[position].group) }) recyclerView.adapter = SingerAdapter(layoutInflater, singerList, R.layout.recycler_row)

完成！此时运行应用，分组标题就会在滚动中自动吸顶。完整可运行代码可参考示例工程 MainActivity.kt。

Compose 版本：用声明式代码搭建吸顶时间轴

如果你在用 Jetpack Compose，对应组件是 StickyTimeLineLazyColumn.kt（竖向）和 StickyTimeLineLazyRow.kt（横向），思路一样：数据 → 分组 → 三个内容槽位。

StickyTimeLineLazyColumn( items = sortedMusicList, groupBy = { it.year }, // 按年份分组 makeHeaderItem = { key, _ -> key }, sectionHeader = { year -> Text(year, style = TextStyle(fontSize = 18.sp, fontWeight = FontWeight.Bold)) }, itemContent = { music -> Card { Column { Text(music.title); Text(music.artist) } } }, timeLineDot = { // 时间轴圆点 Box(Modifier.size(24.dp).background(Color.Gray, CircleShape)) } )

三个槽位各司其职：sectionHeader画分组头（会吸顶）、itemContent画列表项、timeLineDot画圆点。横向布局只需换成StickyTimeLineLazyRow并改写headerContent/dotContent，更多参数见示例工程 sample-compose 的 MainActivity.kt。

常用属性速查：让时间轴更贴合你的设计

View 系统的全部属性定义在 attrs.xml，直接在 XML 里写就能改样式：

举个例子，把时间轴改成粉色主题 + 圆形图标圆点：

<xyz.sangcomz.stickytimelineview.TimeLineRecyclerView android:layout_width="match_parent" android:layout_height="wrap_content" app:timeLineColor="#E91E63" app:timeLineDotColor="#E91E63" app:customDotDrawable="@drawable/ic_buzz" />

实战效果：这些 App 正在使用它

除了官方示例，StickyTimeLine 也已经被多款上架应用采用。

新手避坑指南：3 个注意事项

1. 只支持 LinearLayoutManager：View 版本请搭配LinearLayoutManager使用，Grid 等其他 LayoutManager 暂不支持（吸顶偏移计算依赖线性布局）。
2. 列表项父视图不要设置 margin：间距请交给组件内部处理，否则会干扰吸顶与线条的对齐。
3. 数据要先按分组键排序：isSection/groupBy依赖"同组数据连续排列"，先排序再绑定 Adapter 才能正确分组。

项目结构一览

吸顶逻辑由 VerticalSectionItemDecoration.kt 与 HorizontalSectionItemDecoration.kt 负责绘制线条、圆点并计算吸顶偏移，感兴趣的同学可以直接读源码。

总结

StickyTimeLine 把 Android 里最经典的"分组吸顶列表"做成了开箱即用的组件：View 系统加一个TimeLineRecyclerView、实现两个回调方法，Compose 世界写一个StickyTimeLineLazyColumn，五分钟就能让音乐年表、行情流水、事件时间线获得专业级的吸顶体验。依赖一行、代码几行、效果拉满——这正是它值得一试的理由。🎉

【免费下载链接】StickyTimeLine:book:StickyTimeLine is timeline view for android.项目地址: https://gitcode.com/gh_mirrors/st/StickyTimeLine