HeaderAndFooterRecyclerView

RecyclerView Header/Footer 历史实现与 AndroidX 迁移示例。

English · 历史示例 · 开发指南

这个项目最初用于给 RecyclerView 添加 Header、Footer，并演示分页加载状态。今天，仓库保留可构建的旧实现，同时提供 AndroidX 对照示例，帮助已有项目逐步迁移。

新项目建议直接使用 AndroidX ConcatAdapter 实现 Header/Footer。 需要完整的分页管理时再引入 Paging。已有项目可以逐步替换；本分支不是旧 Android Support 版本的无缝升级。

从这里开始

你的情况	推荐入口
正在开发新的 RecyclerView 页面	运行 samplePlus 中的 ConcatAdapter (AndroidX)，该页面不调用本库 API。
正在维护已经接入本库的项目	查看兼容性与维护范围和历史用法。
查找当年的用法和截图	查看历史用法与截图。
准备贡献代码，或使用 AI 协作	阅读开发指南、架构说明和 AGENTS.md。

今天如何实现这些需求？

需求	推荐方案
Header + 数据 + Footer	ConcatAdapter(headerAdapter, dataAdapter, footerAdapter)
点击事件中的数据位置	getBindingAdapterPosition()，并检查 NO_POSITION
列表增量刷新	ListAdapter / DiffUtil
分页管理与错误重试	Paging + PagingDataAdapter + LoadStateAdapter
网格、瀑布流中占满宽度的 Header/Footer	显式配置跨度或 full-span 布局参数

ConcatAdapter 负责组合 Adapter、转发通知偏移和隔离 viewType，但不会替你决定布局跨度。迁移到 Paging 还需要整理请求和分页状态，不能只替换滚动监听器。参见官方 ConcatAdapter 文档和 Paging 加载状态指南。

运行示例

准备 JDK 17 或 21、Android SDK 36 和 Build Tools 35.0.0。设置 ANDROID_HOME 或在不提交到 Git 的 local.properties 中配置 SDK 路径，详见环境配置。

sdkmanager "platforms;android-36" "build-tools;35.0.0" "platform-tools"
./gradlew testDebugUnitTest assembleDebug lintDebug --console=plain

Windows 使用 gradlew.bat。首次构建需要下载依赖，单元测试在本机运行，无需模拟器。工程固定使用 Gradle 8.13、AGP 8.11.1、RecyclerView 1.4.0 和 AppCompat 1.7.1，所有模块最低支持 Android API 21。

模块	用途
library	保留旧 Adapter 包装器、位置/跨度辅助方法和滚动回调，用于迁移与回归验证。
sample	最小的旧版 Header/Footer 示例。
samplePlus	首项为 AndroidX 网格示例，其后为旧版线性、网格和瀑布流分页演示。

用 Android Studio 打开仓库根目录，运行 samplePlus。进入 ConcatAdapter (AndroidX) 后，可以看到跨两列的 Header/Footer；点击数据项会显示其在数据 Adapter 内的位置。两个示例使用不同的应用 ID，可以同时安装。

现代示例位于 ConcatExampleActivity.java。samplePlus 为保留其他旧演示仍依赖 library，复制现代页面本身不需要旧包装器。仓库没有提供完整的 Paging 或 Compose 应用。

兼容性与维护范围

• 本分支将 android.support 迁移到 AndroidX，并将 library 和 sample 的最低 SDK 从 14 提高到 21。旧版 Support 使用方需要更新导入并重新构建。
• 原始 Support 版本保留在 Git 历史中。本分支不发布或替换 Maven 制品。
• 维护重点是可复现构建、已确认的缺陷、必要的兼容修复，以及文档和示例；不再扩张通用 Adapter 功能。
• 测试和 CI 覆盖已记录的场景，并不代表所有历史边界问题都已解决。已知限制见架构说明，设备验收清单见开发指南。