Paging 3 分页：从手动分页到声明式加载

为什么需要分页

当列表数据量很大时，不可能一次性把所有数据加载到内存中。比如一个新闻列表有上万条数据，一次性加载会导致：

1. 内存溢出。 上万条数据全部持有在内存中，列表滚动时还可能触发更多 GC。
2. 首屏慢。 用户要等所有数据下载完才能看到页面，体验极差。
3. 流量浪费。 用户可能只看前几条，后面的数据根本用不到。

分页加载的思路就是：先加载一小部分数据展示，用户滚动到底部时再自动加载更多。

手动分页的痛点

在 Paging 3 出现之前，很多开发者手动实现分页逻辑：

class NewsAdapter : RecyclerView.Adapter<NewsAdapter.VH>() {
    private val items = mutableListOf<News>()
    private var currentPage = 1
    private var isLoading = false
    private var hasMore = true

    fun loadMore() {
        if (isLoading || !hasMore) return
        isLoading = true
        api.getNews(page = currentPage).enqueue { list ->
            items.addAll(list)
            currentPage++
            hasMore = list.isNotEmpty()
            isLoading = false
            notifyDataSetChanged()
        }
    }
}

这段代码有几个典型问题：

• 状态管理复杂。 isLoading、hasMore、currentPage 等标志位容易出 bug，比如重复请求或漏掉加载。
• 与 RecyclerView 耦合。 分页逻辑散落在 Adapter 和 Fragment/Activity 中，难以测试。
• 错误处理不统一。 加载失败后的重试逻辑需要自己维护。
• 不支持 DiffUtil。 用 notifyDataSetChanged() 做全量刷新，性能差。

Paging 3 把这些繁琐的工作都封装好了。

Paging 3 是什么

Paging 3 是 Android Jetpack 中的分页加载库，核心特点：

1. 基于 Kotlin Coroutines + Flow。 天然支持协程，数据流用 Flow<PagingData<T>> 表示。
2. 自动加载下一页。 监听滚动位置，在合适的时机自动触发加载，不需要手动判断。
3. 内置状态管理。 加载中、加载失败、加载完成等状态都有内置支持，包括 Footer 显示。
4. 支持 DiffUtil。 PagingDataAdapter 内置 DiffUtil，自动做增量更新。
5. 支持多种数据源。 网络、Room 数据库、或者两者结合都行。

添加依赖

在 build.gradle 中：

dependencies {
   
    implementation "androidx.paging:paging-runtime:3.3.0"
    // 如果只用 Compose
    implementation "androidx.paging:paging-compose:3.3.0"
}

核心组件

Paging 3 有三个核心组件：

第一步：定义 PagingSource

PagingSource 是分页的数据来源。对于网络分页，它接收页码，返回一页数据：

class NewsPagingSource(
    private val api: NewsApi
) : PagingSource<Int, News>() {

    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, News> {
        val page = params.key ?: 1
        return try {
            val response = api.getNews(page = page, size = params.loadSize)
            LoadResult.Page(
                data = response.data,
                prevKey = if (page == 1) null else page - 1,
                nextKey = if (response.data.isEmpty()) null else page + 1
            )
        } catch (e: Exception) {
            LoadResult.Error(e)
        }
    }

    override fun getRefreshKey(state: PagingState<Int, News>): Int? {
        return state.anchorPosition?.let { pos ->
            state.closestPageToPosition(pos)?.prevKey?.plus(1)
                ?: state.closestPageToPosition(pos)?.nextKey?.minus(1)
        }
    }
}

几个要点：

• LoadParams.key 是页码，首次加载时为 null，我们用默认值 1。
• prevKey / nextKey 告诉 Paging 框架上一页和下一页的 key。如果到头了就返回 null。
• getRefreshKey 用于刷新（如下拉刷新）后恢复滚动位置。

第二步：用 Pager 创建数据流

在 ViewModel 中用 Pager 把 PagingSource 包装成 Flow<PagingData<T>>：

class NewsViewModel(private val api: NewsApi) : ViewModel() {

    val newsFlow: Flow<PagingData<News>> = Pager(
        config = PagingConfig(
            pageSize = 20,           // 每页 20 条
            prefetchDistance = 5,    // 距离底部 5 条时预加载
            initialLoadSize = 40,    // 首次加载 40 条
            enablePlaceholders = false
        )
    ) {
        NewsPagingSource(api)
    }.flow.cachedIn(viewModelScope)
}

关键参数：

• pageSize： 每次加载的数据量。
• prefetchDistance： 距离末尾多少条时开始预加载下一页。
• initialLoadSize： 首次加载的数据量，通常设为 pageSize 的 2-3 倍，让用户看到更充实的首屏。
• cachedIn(viewModelScope)： 将 Flow 缓存在 ViewModel 的生命周期内，避免配置变化后重新加载。

第三步：用 PagingDataAdapter 展示

class NewsAdapter : PagingDataAdapter<News, NewsAdapter.VH>(DIFF_CALLBACK) {

    companion object {
        val DIFF_CALLBACK = object : DiffUtil.ItemCallback<News>() {
            override fun areItemsTheSame(old: News, new: News) = old.id == new.id
            override fun areContentsTheSame(old: News, new: News) = old == new
        }
    }

    inner class VH(view: View) : RecyclerView.ViewHolder(view) {
        val title: TextView = view.findViewById(R.id.tv_title)
    }

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): VH {
        val view = LayoutInflater.from(parent.context)
            .inflate(R.layout.item_news, parent, false)
        return VH(view)
    }

    override fun onBindViewHolder(holder: VH, position: Int) {
        val news = getItem(position)
        news?.let { holder.title.text = it.title }
    }
}

在 Fragment 中收集数据：

viewLifecycleOwner.lifecycleScope.launch {
    viewModel.newsFlow.collectLatest { pagingData ->
        adapter.submitData(pagingData)
    }
}

collectLatest 会在新的 PagingData 到来时取消上一次收集，确保下拉刷新时旧数据被替换。

处理加载状态

Paging 3 内置了加载状态管理，可以通过 adapter.loadStateFlow 监听：

adapter.addLoadStateListener { loadState ->
    // 首次加载
    if (loadState.refresh is LoadState.Loading) {
        binding.progressBar.isVisible = true
    } else {
        binding.progressBar.isVisible = false
    }

    // 加载失败
    val error = when {
        loadState.refresh is LoadState.Error -> loadState.refresh as LoadState.Error
        loadState.append is LoadState.Error -> loadState.append as LoadState.Error
        else -> null
    }
    error?.let {
        Toast.makeText(requireContext(), "加载失败：${it.error.message}", Toast.LENGTH_SHORT).show()
    }
}

添加 Footer（加载中/失败/重试）

创建一个 LoadStateAdapter 作为 Footer：

class PagingLoadStateAdapter(
    private val retry: () -> Unit
) : LoadStateAdapter<PagingLoadStateAdapter.VH>() {

    inner class VH(view: View) : RecyclerView.ViewHolder(view) {
        val progressBar: ProgressBar = view.findViewById(R.id.progress)
        val errorMsg: TextView = view.findViewById(R.id.error_msg)
        val retryBtn: Button = view.findViewById(R.id.retry_btn)
    }

    override fun onCreateViewHolder(parent: ViewGroup, loadState: LoadState): VH {
        val view = LayoutInflater.from(parent.context)
            .inflate(R.layout.item_load_state, parent, false)
        return VH(view).apply {
            retryBtn.setOnClickListener { retry() }
        }
    }

    override fun onBindViewHolder(holder: VH, loadState: LoadState) {
        holder.progressBar.isVisible = loadState is LoadState.Loading
        holder.errorMsg.isVisible = loadState is LoadState.Error
        holder.retryBtn.isVisible = loadState is LoadState.Error
    }
}

把它合并到主 Adapter 上：

val adapterWithFooter = adapter.withLoadStateFooter(
    PagingLoadStateAdapter { adapter.retry() }
)
recyclerView.adapter = adapterWithFooter

这样列表底部就会自动显示"加载中"或"加载失败 + 重试按钮"。

Room + Paging 3

当数据源是本地数据库时，Room 直接支持 Paging 3：

@Dao
interface NewsDao {
    @Query("SELECT * FROM news ORDER BY publishTime DESC")
    fun pagingSource(): PagingSource<Int, News>
}

ViewModel 中直接使用：

val newsFlow = Pager(
    config = PagingConfig(pageSize = 20)
) {
    newsDao.pagingSource()
}.flow.cachedIn(viewModelScope)

Room 会自动处理数据库变更后的自动刷新——当数据表有 INSERT/UPDATE/DELETE 操作时，PagingSource 会自动重新加载。

网络 + 本地联合分页

最常见的架构是"网络请求 → 写入 Room → 从 Room 读取展示"。Paging 3 提供了 RemoteMediator 来实现这种模式：

class NewsRemoteMediator(
    private val api: NewsApi,
    private val db: AppDatabase
) : RemoteMediator<Int, News>() {

    override suspend fun load(
        loadType: LoadType,
        state: PagingState<Int, News>
    ): MediatorResult {
        val page = when (loadType) {
            LoadType.REFRESH -> 1
            LoadType.PREPEND -> return MediatorResult.Success(endOfPaginationReached = true)
            LoadType.APPEND -> {
                val lastItem = state.lastItemOrNull() ?: return MediatorResult.Success(true)
                lastItem.pageIndex + 1
            }
        }

        return try {
            val response = api.getNews(page = page, size = state.config.pageSize)
            db.withTransaction {
                if (loadType == LoadType.REFRESH) {
                    db.newsDao().clearAll()
                }
                db.newsDao().insertAll(response.data)
            }
            MediatorResult.Success(endOfPaginationReached = response.data.isEmpty())
        } catch (e: Exception) {
            MediatorResult.Error(e)
        }
    }
}

使用方式：

val newsFlow = Pager(
    config = PagingConfig(pageSize = 20),
    remoteMediator = NewsRemoteMediator(api, db)
) {
    db.newsDao().pagingSource()
}.flow.cachedIn(viewModelScope)

这样用户看到的始终是 Room 中的数据，网络请求在后台自动进行，离线时也能展示缓存数据。

下拉刷新

下拉刷新只需要让 adapter 重新提交数据：

binding.swipeRefresh.setOnRefreshListener {
    adapter.refresh()
}

// 监听刷新状态，自动关闭刷新动画
adapter.addLoadStateListener { loadState ->
    binding.swipeRefresh.isRefreshing = loadState.refresh is LoadState.Loading
}

adapter.refresh() 会触发 PagingSource 的 LoadType.REFRESH，从第一页重新开始加载。

常见问题

Q：列表位置在刷新后丢失了怎么办？

A：确保 getRefreshKey() 正确实现。Paging 3 会根据它恢复滚动位置。

Q：如何实现按时间分组（Header）？

A：在 PagingData 上做 map 转换，插入分组标题项：

newsFlow.map { pagingData ->
    pagingData.map { news -> NewsItem.Content(news) }
}.map { pagingData ->
    pagingData.insertSeparators { before, after ->
        if (before == null && after != null) {
            NewsItem.Header("最新")
        } else if (before != null && after != null && before.news.date != after.news.date) {
            NewsItem.Header(after.news.date)
        } else null
    }
}

Q：pageSize 设多大合适？

A：通常一屏能展示 5-8 条数据，pageSize 设为 15-25 比较合适。太大浪费流量，太小频繁请求。

小结

Paging 3 把分页加载这个常见需求标准化了。它的核心思路是：

1. PagingSource 负责定义数据从哪来、怎么翻页。
2. Pager 负责配置加载策略，输出 Flow<PagingData>。
3. PagingDataAdapter 负责消费数据并展示，自动处理 DiffUtil 和滚动监听。

配合 LoadStateAdapter 和 RemoteMediator，可以覆盖从简单网络分页到"网络 + 本地缓存"联合分页的各种场景。如果你还在手动管理分页状态，是时候切换到 Paging 3 了。