NestRecyclerView_V2

KO | EN

gitlite — search

#ai #typescript #llm #golang #machine-learning #rust #linux #docker #macos #awesome #cli #kubernetes #vue #pytorch

NestRecyclerView_V2

(★ 20)

仿京东、淘宝首页通过Tab的吸顶效果（方案二）

NestRecyclerView_V2 Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# NestRecyclerView

一个基于 Kotlin 编写的 Android 示例项目，用来演示 `RecyclerView` 嵌套滚动、Tab 吸顶、`ViewPager + RecyclerView` 联动等常见首页场景的实现方式。

项目重点不在于封装成通用组件，而在于展示一套清晰的嵌套滚动页面架构，方便理解父子 `RecyclerView`、Tab 吸顶以及分页内容之间的协作方式。

## 效果预览

### 示例动画

![示例动画](https://raw.githubusercontent.com/Ubitar/NestRecyclerView_V2/master/screenshot/示例.gif)

### 下载二维码

![下载二维码](https://raw.githubusercontent.com/Ubitar/NestRecyclerView_V2/master/screenshot/下载二维码.png)

## 功能特性

- 外层 `NestRecyclerView` 承载主页面内容
- 内层 `NestChildRecyclerView` 承载分页列表内容
- 支持 Tab 区域吸顶
- 支持 `ViewPager` 与 Tab 选中状态联动
- 支持嵌套滚动中的 fling 速度衔接
- 支持内层列表滚动到底部的回调扩展
- 集成 `SmartRefreshLayout`，便于继续扩展下拉刷新/上拉加载

## 运行环境

- Android Studio Hedgehog 或更高版本
- JDK 17
- Gradle Plugin `8.2.2`
- Kotlin `1.9.22`
- `compileSdk 34`
- `minSdk 21`
- `targetSdk 34`

## 架构概览

页面整体采用“单 Activity + 外层主列表 + 内层分页列表”的结构。核心目标是把首页内容区、吸顶 Tab 区和分页列表区组织到同一套滚动体系中。

```text
MainActivity
  └─ SmartRefreshLayout
      └─ NestRecyclerView
          └─ MainAdapter
              ├─ 普通内容区（TYPE_MAIN）
              └─ 子内容区（TYPE_SUB）
                  ├─ TabAdapter
                  └─ ViewPager
                      ├─ NestChildRecyclerView + SubAdapter
                      ├─ NestChildRecyclerView + SubAdapter
                      ├─ NestChildRecyclerView + SubAdapter
                      └─ NestChildRecyclerView + SubAdapter
```

## 架构分层

### 页面层

`MainActivity` 负责组装页面和事件，是整个示例的入口。

- 初始化 `NestRecyclerView` 和 `MainAdapter`
- 构造演示数据，包括主列表项、Tab 数据和分页列表数据
- 绑定 Tab 点击、分页切换、子列表滚动到底部等事件

### 容器层

容器层的职责是解决父子列表之间的嵌套滚动与手势分发问题，核心类位于 `ry` 包下。

`BaseRecyclerView`

- 作为父子列表共同的基类
- 通过反射读取 `RecyclerView` 内部 fling 速度
- 提供停止 fling 和获取当前纵向速度的能力

`NestRecyclerView`

- 外层主列表容器
- 实现 `NestedScrollingParent3`
- 控制父容器优先滚动还是子容器优先滚动
- 维护吸顶区域高度和子分页容器高度
- 在外层滚动停止时把剩余惯性传给当前子列表

`NestChildRecyclerView`

- 内层分页列表容器
- 区分水平滑动和垂直滑动，减少与 `ViewPager` 的手势冲突
- 在子列表回滚到顶部时，把剩余 fling 速度交还给父列表
- 挂载时自动向上查找并绑定 `NestRecyclerView`

### 适配层

适配层负责把页面数据映射成可滚动的 UI 结构。

`MainAdapter`

- 作为外层列表适配器
- 通过 `TYPE_MAIN` 和 `TYPE_SUB` 组织不同类型的页面区块
- 实现 `NestRecyclerView.INestAdapter`
- 创建并管理当前页的 `NestChildRecyclerView`
- 负责 Tab、`ViewPager`、子列表三者之间的联动

`TabAdapter`

- 管理横向 Tab 展示和选中状态

`SubAdapter`

- 管理每个分页内的列表项展示

`VViewPagerAdapter`

- 承载多个 `NestChildRecyclerView` 页面

### 数据层

数据层很轻，主要用于表达页面结构。

`MainListBean`

- 定义外层列表中的两种区块类型
- `TYPE_MAIN` 表示普通内容项
- `TYPE_SUB` 表示包含 Tab 和分页列表的嵌套区块

`MainTabBean`

- 表示单个 Tab 的标题和选中状态

## 核心滚动链路

这个项目的关键不只是“嵌套列表”，而是滚动控制权在父子容器之间如何切换。

1. 页面先由外层 `NestRecyclerView` 承担主滚动
2. 当子内容区到达吸顶位置后，滚动控制权逐渐转交给当前页的 `NestChildRecyclerView`
3. 子列表继续向上滚动时，由子列表消费滚动距离
4. 子列表回到顶部并继续下拉时，剩余滚动和 fling 再回传给外层列表
5. `ViewPager` 负责分页切换，`TabAdapter` 负责同步当前选中态

这套链路的核心价值在于让页面在视觉上表现为一个连续整体，而不是多个互相抢事件的滚动区域。

## 项目结构

```text
app/src/main/java/com/example/nestrecyclerview/demo2
├─ MainActivity.kt                  // 页面入口，负责装配数据与交互
├─ App.kt                           // Application 初始化
├─ adapter
│  ├─ MainAdapter.kt                // 外层主列表适配器，串联 Tab / ViewPager / 子列表
│  ├─ SubAdapter.kt                 // 分页子列表适配器
│  ├─ TabAdapter.kt                 // 吸顶 Tab 适配器
│  └─ VViewPagerAdapter.kt          // ViewPager 页面适配器
├─ bean
│  ├─ MainListBean.kt               // 外层列表数据模型
│  └─ MainTabBean.kt                // Tab 数据模型
└─ ry
   ├─ BaseRecyclerView.kt           // 父子列表公共基类
   ├─ NestRecyclerView.kt           // 外层 RecyclerView，负责嵌套滚动分发
   └─ NestChildRecyclerView.kt      // 内层 RecyclerView，负责子列表滚动与回传
```

## 主要依赖

- `androidx.recyclerview:recyclerview:1.3.2`
- `io.github.cymchad:BaseRecyclerViewAdapterHelper:3.0.14`
- `io.github.scwang90:refresh-layout-kernel:2.0.6`
- `io.github.scwang90:refresh-header-classics:2.0.6`
- `com.blankj:utilcode:1.30.7`

## 适用场景

这套架构比较适合以下页面：

- 个人主页、店铺首页、内容频道页
- 顶部有静态内容区，中间有吸顶 Tab，底部有分页列表
- 需要父列表与子列表共享一套自然连续的滚动体验

## 相关文章

简书文章：

https://www.jianshu.com/p/0e91648173dc

## 说明

这个仓库是一个偏“架构演示”的示例工程，核心价值在于嵌套滚动处理思路、职责拆分方式，以及页面结构的组织方式。如果你准备在生产项目中使用，建议结合自己的业务场景进一步补充：

- 刷新和加载更多状态管理
- 页面状态恢复
- 更复杂的数据分页缓存
- `ViewPager2` 适配
- 边界场景下的兼容性测试

NestRecyclerView_V2

NestRecyclerView_V2 Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

NestRecyclerView_V2

NestRecyclerView_V2 Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README