Paging 3 用于 Kotlin：完整指南及示例

1. 什么是 Paging 3 以及为什么需要它

Paging 3 是 Google 为 Android 开发的一个库，使用 Kotlin 编写，它解决了移动开发中最常见的问题之一：分页加载数据（pagination）。当您有一个包含数千或数百万个元素的列表（例如，新闻提要、聊天消息、目录中的商品）时，一次性全部加载是不可能的——这会导致内存溢出、UI 卡顿以及巨大的流量消耗。Paging 3 自动化了随着用户滚动列表而分批（按页）加载数据的过程。

该库基于现代原则构建：它使用 Kotlin 协程进行异步操作，使用 Flow 进行响应式数据更新，并与 Jetpack Compose 和 RecyclerView 完全集成。与之前的版本（Paging 2）相比，Paging 3 提供了更清晰的架构、更少的样板代码，以及内置的错误处理、数据更新和缓存支持。

Paging 3 的主要价值在于：您只需编写加载单个页面的逻辑（例如，API 请求），而库本身会决定何时请求下一页、如何在内存中存储数据、如何通知适配器有关更改以及如何处理加载状态（加载中、错误、空列表）。这节省了数小时的开发时间，并使您的应用即使在处理海量数据集时也能保持稳定。

2. 安装

Paging 3 是一个 Android/Kotlin 库，因此它通过 Gradle 构建系统安装，而不是通过 pip 或 npm。将依赖项添加到 build.gradle.kts 文件（app 模块）中：

// build.gradle.kts (Module: app)\ndependencies {\n    // Paging 3 核心库\n    implementation("androidx.paging:paging-runtime-ktx:3.3.5")\n    \n    // 如果您使用 Jetpack Compose（可选）\n    implementation("androidx.paging:paging-compose:3.3.5")\n    \n    // 如果您使用 RxJava（可选）\n    implementation("androidx.paging:paging-rxjava3:3.3.5")\n    \n    // 用于测试（可选）\n    testImplementation("androidx.paging:paging-common:3.3.5")\n}\n

同步 Gradle 后，该库即可使用。最低 SDK 版本为 21（Android 5.0）。

3. 快速入门——最小工作示例

让我们创建一个最简单的界面，它加载一个从 1 到 1000 的数字列表，每页 20 个元素。该示例由三部分组成：数据源（PagingSource）、ViewModel 和 UI（RecyclerView）。

步骤 1. PagingSource——数据源

class NumberPagingSource : PagingSource<Int, Int>() {\n    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, Int> {\n        return try {\n            // 确定下一页的键（如果为 null，则是首次加载）\n            val currentPage = params.key ?: 0\n            val pageSize = params.loadSize  // 通常为 20\n            \n            // 为当前页面生成数据\n            val start = currentPage * pageSize\n            val end = minOf(start + pageSize, 1000)\n            val numbers = (start until end).toList()\n            \n            // 返回结果，包含下一页和上一页的键\n            LoadResult.Page(\n                data = numbers,\n                prevKey = if (currentPage > 0) currentPage - 1 else null,\n                nextKey = if (end < 1000) currentPage + 1 else null\n            )\n        } catch (e: Exception) {\n            LoadResult.Error(e)\n        }\n    }\n    \n    // 返回用于刷新的键（通常为 null 或第一个键）\n    override fun getRefreshKey(state: PagingState<Int, Int>): Int? = null\n}\n

步骤 2. ViewModel

class MainViewModel : ViewModel() {\n    val pager = Pager