Paging

此表列出了 androidx.paging 组中的所有工件。

声明依赖项

要添加 Paging 依赖项，您必须将 Google Maven 代码库添加到您的项目。有关详情，请阅读Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需的工件依赖项

dependencies {
  def paging_version = "3.3.6"

  implementation "androidx.paging:paging-runtime:$paging_version"

  // alternatively - without Android dependencies for tests
  testImplementation "androidx.paging:paging-common:$paging_version"

  // optional - RxJava2 support
  implementation "androidx.paging:paging-rxjava2:$paging_version"

  // optional - RxJava3 support
  implementation "androidx.paging:paging-rxjava3:$paging_version"

  // optional - Guava ListenableFuture support
  implementation "androidx.paging:paging-guava:$paging_version"

  // optional - Jetpack Compose integration
  implementation "androidx.paging:paging-compose:3.3.6"
}

dependencies {
  val paging_version = "3.3.6"

  implementation("androidx.paging:paging-runtime:$paging_version")

  // alternatively - without Android dependencies for tests
  testImplementation("androidx.paging:paging-common:$paging_version")

  // optional - RxJava2 support
  implementation("androidx.paging:paging-rxjava2:$paging_version")

  // optional - RxJava3 support
  implementation("androidx.paging:paging-rxjava3:$paging_version")

  // optional - Guava ListenableFuture support
  implementation("androidx.paging:paging-guava:$paging_version")

  // optional - Jetpack Compose integration
  implementation("androidx.paging:paging-compose:3.3.6")
}

有关使用 Kotlin 扩展的信息，请参阅ktx 文档。

如需详细了解依赖项，请参阅添加构建依赖项。

反馈

您的反馈有助于改进 Jetpack。如果您发现了新问题或对改进此库有任何想法，请告知我们。在创建新问题之前，请先查看此库中的现有问题。您可以点击星形按钮为您关注的现有问题添加投票。

创建新问题

有关详情，请参阅问题跟踪器文档。

版本 3.3

版本 3.3.6

2025 年 2 月 12 日

androidx.paging:paging-*:3.3.6 发布。版本 3.3.6 包含这些提交。

bug 修复

• 初始 Refresh 期间发送的刷新和重试信号现将存储，并在 Paging presenter 准备就绪后自动重新发送。

外部贡献

• 感谢 Eva 提交 bug 修复 (#754)

版本 3.3.5

2024 年 12 月 11 日

androidx.paging:paging-*:3.3.5 发布。版本 3.3.5 包含这些提交。

bug 修复

• 修复了用户在更新 RecyclerView 时滚动导致 RecyclerView 抛出 IndexOutOfBoundsException 错误的问题。(Id1f16, b/381024738)

版本 3.3.4

2024 年 11 月 13 日

androidx.paging:paging-*:3.3.4 发布。版本 3.3.4 包含这些提交。

bug 修复

• 引入 Paging 3.3 或更高版本的 Android 单元测试将不再抛出 Method isLoggable in android.util.Log not mocked 之类的错误。(Ia9400, b/331684448)

版本 3.3.2

2024 年 8 月 7 日

androidx.paging:paging-*:3.3.2 发布。版本 3.3.2 包含这些提交。

新功能

• paging-common 和 paging-testing 添加了新的 Kotlin 多平台目标：watchos、tvos 和 linuxArm64 (90c9768)、(53e0eca)

版本 3.3.1

2024 年 7 月 24 日

androidx.paging:paging-*:3.3.1 发布。版本 3.3.1 包含这些提交。

bug 修复

• 修复了使用 RecyclerView 时，基础数据源在滚动时刷新，导致 AsyncPagingDataDiffer 或在其之上构建的 API（如 PagingDataAdapter）无法触发更多加载的问题。(I60ca5, b/352586078)
• 修复了使用 PagingDataAdapter 或 AsyncPagingDataDiffer 滚动 RecyclerView 时，基础数据源中的项目被移除时发生的崩溃。(I8c65a, b/347649763)

版本 3.3.0

2024 年 5 月 14 日

androidx.paging:paging-*:3.3.0 发布。版本 3.3.0 包含这些提交。

自 3.2.0 以来的重要变更

• PagingDataPresenter 现在是一个公共类。现在可以在 PagingDataPresenter 的基础上构建多平台 presenter，而无需内部 Paging API 或 paging-runtime 的 AsyncPagingDataDiffer。
• 在 hasError 和 isIdle 中添加了新的 LoadStates 和 CombinedLoadStates 辅助方法，分别用于检查 LoadStates 是否处于 Error 或 NotLoading 状态。还在 Flow<CombinedLoadStates> 上添加了新的 awaitNotLoading() Kotlin 扩展方法，该方法会等待加载稳定到 NotLoading 或 Error 状态。
• 默认情况下，PagingData.empty() 现在会分派 NotLoading 状态，除非在其构造函数中传递了自定义 LoadStates。这与现有的行为有所不同，现有行为在提交给 PagingDataAdapter 时不分派 LoadStates，或者在收集为 LazyPagingItems 时分派 Loading 状态。当收集为 LazyPagingItems 时，它现在还会在初始组合后立即显示一个空列表。

Kotlin 多平台兼容性

Paging 现在发布兼容 Kotlin 多平台的工件，这主要归功于 CashApp 的 multiplatform-paging 项目上游工作。

• paging-common 已将其所有 Paging 3 API 移至 common，现在除 Android 外，还兼容 jvm 和 iOS。
• paging-testing 已将其代码移至 common，现在除 Android 外，还兼容 jvm 和 iOS。
• paging-compose 已将其代码移至 common 并发布 Android 工件，与 androidx.compose 的多平台支持相匹配。
• paging-runtime、paging-guava、paging-rxjava2 和 paging-rxjava3 将仍然仅支持 Android。

版本 3.3.0-rc01

2024 年 5 月 1 日

androidx.paging:paging-*:3.3.0-rc01 发布，与 Paging 3.3.0-beta01 无任何变更。版本 3.3.0-rc01 包含这些提交。

版本 3.3.0-beta01

2024 年 4 月 3 日

androidx.paging:paging-*:3.3.0-beta01 发布，无显著变化。版本 3.3.0-beta01 包含这些提交。

版本 3.3.0-alpha05

2024 年 3 月 20 日

androidx.paging:paging-*:3.3.0-alpha05 发布。版本 3.3.0-alpha05 包含这些提交。

API 变更

• Paging 现在对通用代码使用 AndroidX Annotation @MainThread 注解。(I78f0d, b/327682438)

版本 3.3.0-alpha04

2024 年 3 月 6 日

androidx.paging:paging-*:3.3.0-alpha04 发布。版本 3.3.0-alpha04 包含这些提交。

bug 修复

• 修复了与添加 Kotlin 多平台兼容性相关的次要文档错误。(aosp/2950785)

版本 3.3.0-alpha03

2024 年 2 月 7 日

androidx.paging:paging-*:3.3.0-alpha03 发布。版本 3.3.0-alpha03 包含这些提交。

新功能

• PagingDataPresenter 现在是一个公共类。现在可以在 PagingDataPresenter 的基础上构建多平台 presenter，而无需内部 Paging API 或 paging-runtime 的 AsyncPagingDataDiffer。(Id1f74, b/315214786)
• 添加了新的 LoadStates 和 CombinedLoadStates 辅助方法，用于检查 LoadStates 是否处于 Error 或 NotLoading 状态。还添加了一个新的 API，该 API 会在 LoadStateFlow 上等待加载稳定到 NotLoading 或 Error 状态。(Id6c67)

行为变更

• 默认情况下，PagingData.empty() 现在会分派 NotLoading 状态，除非在其构造函数中传递了自定义 LoadStates。这与现有的行为有所不同，现有行为在提交给 PagingDataAdapter 时不分派 LoadStates，或者在收集为 LazyPagingItems 时分派 Loading 状态。当收集为 LazyPagingItems 时，它现在还会在初始组合后立即显示一个空列表。(I4d11d, b/301833847)

版本 3.3.0-alpha02

2023 年 9 月 20 日

androidx.paging:paging-*:3.3.0-alpha02 发布。版本 3.3.0-alpha02 包含这些提交。

Kotlin 多平台兼容性

Paging 现在发布兼容 Kotlin 多平台的工件，这主要归功于 CashApp 的 multiplatform-paging 项目上游工作。这将有助于我们避免两个代码库之间出现差异，并保持它们兼容。

• paging-common 已将其所有 Paging 3 API 移至 common，现在除 Android 外，还兼容 jvm 和 iOS。
• paging-testing 已将其代码移至 common，现在除 Android 外，还兼容 jvm 和 iOS。
• paging-compose 已将其代码移至 common 并发布 Android 工件，与 androidx.compose 的多平台支持相匹配。
• paging-runtime、paging-guava、paging-rxjava2 和 paging-rxjava3 将仍然仅支持 Android。

API 变更

• 原本仅供内部使用的公共 Logger 接口已被废弃 (I16e95, b/288623117)

外部贡献

• 感谢 Cash App 的 veyndan 帮助将 Paging 迁移到 Kotlin 多平台 (#560, #561, #562, #573, #576, #577, #578, #579, #580, #581, #583, #584, #586, #609)

版本 3.3.0-alpha01

2023 年 9 月 20 日

• 这是 androidx.paging 库的第一个多平台版本。此版本仅包含 *-jvm 和 *-android 工件。对于 macOS、iOS 和 linux 变体，请使用 3.3.0-alpha02。

版本 3.2

版本 3.2.1

2023 年 9 月 6 日

androidx.paging:paging-*:3.2.1 发布。版本 3.2.1 包含这些提交。

bug 修复

• 修复了 Paging Testing 工件的 asSnapshot() API 在传递使用 PagingData.from(List) 构建的 Flow 时会挂起的问题，因为 asSnapshot() 不会获取任何关于加载何时完成的信息（不像 PagingData.from(List, LoadStates) 重载）。此解决方法仅适用于可完成的 Flow（例如 flowOf(PagingData.from(...))）。对于不可完成的 Flow（例如 MutableStateFlow），请使用提供 LoadStates 的 PagingData.from 重载。(I502c3)
• Paging Compose 现在内部使用 AndroidUiDispatcher.Main，以确保在新数据可用的同一帧中加载完成。(Ia55af)

版本 3.2.0

2023 年 7 月 26 日

androidx.paging:paging-*:3.2.0 发布。版本 3.2.0 包含这些提交。

自 3.1.0 以来的重要变更

• Paging Compose 达到了 API 稳定性，并已合并回 Paging 的其余部分，其版本现在与所有其他 Paging 工件相匹配。自 3.1.0 以来的变更包括
  • 支持通过创建 PagingData.from(fakeData) 并将该 PagingData 封装在 MutableStateFlow 中（例如 MutableStateFlow(PagingData.from(listOf(1, 2, 3)))）来预览虚假数据列表。将此 Flow 传递给 @Preview 可组合项作为 collectAsLazyPagingItems() 的接收器进行预览。
  • 支持所有 lazy 布局，例如 LazyVerticalGrid 和 HorizontalPager，以及 Wear 和 TV 库中的自定义 lazy 组件。这是通过新的底层 LazyPagingItems 扩展方法 itemKey 和 itemContentType 实现的，这些方法可帮助您实现 key 和 contentType 参数，这些参数已存在于 LazyColumn、LazyVerticalGrid 以及 HorizontalPager 等 API 的标准 items API 中。
  • 已废弃仅支持 LazyListScope 的 items(lazyPagingItems) 和 itemsIndexed(lazyPagingItems)。
• 新的 paging-testing 工件，提供了旨在独立单元测试应用的每一层及其与 Paging 集成的 API。例如，它包括
  • TestPager 类，可让您独立于 Pager 和真实 UI 验证您自己的自定义 PagingSource 实现的行为。
  • ​​asPagingSourceFactory API，用于将 Flow<List<Value>> 或静态 List<Value> 转换为可在测试中传递给 Pager 的 PagingSourceFactory
  • Flow<PagingData<Value>> 上的 asSnapshot Kotlin 扩展，它将 Flow<PagingData<Value>> 转换为直接的 List<Value>。asSnapshot lambda 允许您通过 scrollTo 或 appendScrollWhile 等 API 模拟应用 UI，以便您可以验证分页数据集中任何点的快照数据是否正确。
• 添加了默认日志，用于在两个级别（VERBOSE 和 DEBUG）公开 Paging 调试信息。可以通过命令 adb shell setprop log.tag.Paging [DEBUG|VERBOSE] 启用日志。这适用于使用视图的 Paging 和使用 Compose 的 Paging。
• 添加了接受 CoroutineContext 而非 CoroutineDispatcher 的 PagingDataAdapter 和 AsyncPagingDataDiffer 构造函数。
• 添加了一个新的 PagingSourceFactory 函数式接口，它提供了比以前的 () -> PagingSource lambda 更明确的 API 表面。此工厂可用于实例化 Pager。

版本 3.2.0-rc01

2023 年 6 月 21 日

androidx.paging:paging-*:3.2.0-rc01 发布。版本 3.2.0-rc01 包含这些提交。

外部贡献

• 感谢 Veyndan 为将 Paging 移出 Android/JVM 特性做出的贡献。(#553, #554, #555, #559)

版本 3.2.0-beta01

2023 年 6 月 7 日

androidx.paging:paging-*:3.2.0-beta01 发布。版本 3.2.0-beta01 包含这些提交。

Paging Compose

• Paging Compose 已正式达到 API 稳定性。因此，版本已从 1.0.0-alpha20 更新为与其他所有 Paging 工件版本匹配。

API 变更

• 从 Paging Compose 中移除已废弃的 items(LazyPagingItems) 和 itemsIndexed(LazyPagingItems) API。有关其替换 API 的示例，请参阅Paging Compose 1.0.0-alpha20 版本说明。(I9626e)

版本 3.2.0-alpha06

2023 年 5 月 24 日

androidx.paging:paging-*:3.2.0-alpha06 发布。版本 3.2.0-alpha06 包含这些提交。

新功能

• 添加了一个新的 PagingSourceFactory 函数式接口，它提供了比现有 () -> PagingSource lambda 更明确的 API 表面。此工厂可用于实例化 Pager。(I33165, b/280655188)
• 添加了新的 paging-testing API List<Value>.asPagingSourceFactory()，用于获取仅从不可变数据列表加载的 PagingSourceFactory。现有 Flow<List<Value>> 上的扩展仍应用于使用多代静态数据进行测试。(Id34d1, b/280655188)

API 变更

• paging-testing 中的所有公共 API 现在都使用 @VisibleForTesting 进行注解，以确保这些 API 仅在测试中使用。(I7db6e)
• asSnapshot API 不再需要传递 CoroutineScope。它现在默认使用从其父范围继承的上下文。(Id0a78, b/282240990)
• 重新排列了 TestPager 构造函数参数，以直观地匹配真实 Pager 构造函数参数的顺序 (I6185a)
• 将 paging-testing 使用的 lambda 类型 () -> PagingSource<Key, Value> 迁移到类型 PagingSourceFactory<Key, Value>。(I4a950, b/280655188)

行为变更

• 运行 asSnapshot Paging 测试不再需要 Main dispatcher。设置它不会对测试行为产生任何改变。(Ie56ea)

版本 3.2.0-alpha05

2023 年 5 月 3 日

androidx.paging:paging-*:3.2.0-alpha05 发布。版本 3.2.0-alpha05 包含这些提交。

API 变更

• Paging Testing API asSnapshot 现在将其 loadOperations 参数默认为空 lambda。这允许调用 asSnapshot 时不传递任何加载操作，以检索初始刷新加载的数据。(Ied354, b/277233770)

文档改进

• 更新了 asPagingSourceFactory() 的文档，以澄清它是一个 Flow 上的扩展方法，返回一个可重用的工厂，用于生成 PagingSource 实例。(I5ff4f, I705b5)
• 更新了 LoadResult.Page 构造函数的文档，以澄清需要覆盖 itemsBefore 和 itemsAfter 来支持跳转。(Ied354)

外部贡献

• 感谢 Veyndan 为将 Paging 移出 Android/JVM 特性做出的贡献。(#525, #523, #520, #519, #507, #506, #505, #499, #497, #496, #493)

版本 3.2.0-alpha04

2023 年 2 月 8 日

androidx.paging:paging-*:3.2.0-alpha04 发布。版本 3.2.0-alpha04 包含这些提交。

Paging Testing

• paging-testing 工件现在包含一个 asPagingSourceFactory 方法，用于从 Flow<List<Value>> 创建一个 pagingSourceFactory，以提供给 Pager。Flow 中发出的每个 List<Value>> 都代表一代分页数据。这有助于对 PagingData 转换进行分页测试，例如通过模拟 Pager 从中收集数据的数据源。(I6f230, b/235528239)

• 扩展了 paging-testing 工件，新增了适用于验证 Flow<PagingData<T>> 中包含的数据是否正确的 API。例如，这可用于断言 ViewModel 层中 Flow<PagingData<T>> 的输出。

  这是通过 Flow<PagingData<Value>> 上的 asSnapshot Kotlin 扩展完成的，它将 Flow<PagingData<Value>> 转换为直接的 List<Value>。asSnapshot lambda 允许您通过 scrollTo 或 appendScrollWhile 等 API 模拟应用 UI，其方式是可重复且一致的，以便您可以验证分页数据集中任何点的快照数据是否正确。

  // Create your ViewModel instance
  val viewModel = …
  // Get the Flow of PagingData from the ViewModel
  val data< Flow<PagingData<String>> = viewModel.data
  val snapshot: List<String> = data.asSnapshot {
    // Each operation inside the lambda waits for the data to settle before continuing
    scrollTo(index = 50)
  
    // While you can’t view the items within the asSnapshot call,
    // you can continuously scroll in a direction while some condition is true
    // i.e., in this case until you hit a placeholder item
    appendScrollWhile {  item: String -> item != “Header 1” }
  }
  // With the asSnapshot complete, you can now verify that the snapshot
  // has the expected values
  

  asSnapshot 是一个 suspend 方法，应在 runTest 内运行。有关详细信息，请参阅在 Android 上测试 Kotlin 协程。(I55fd2, I5bd26, I7ce34, I51f4d, I2249f, Id6223, Ic4bab, Ib29b9, Ic1238, I96def, b/235528239)

API 变更

• AsyncPagingDataDiffer 和 PagingDataAdapter 中的 getItem 和 peek UI 调用现在正确标记为只能在 Main 线程上调用。(I699b6)
• 从 TestPager 使用的泛型类型中移除了通配符，以便更轻松地使用 Java 编程语言编写的代码中使用这些方法的结果。(I56c42)

版本 3.2.0-alpha03

2022 年 10 月 24 日

androidx.paging:paging-*:3.2.0-alpha03 发布。版本 3.2.0-alpha03 包含这些提交。

Paging Testing

此版本包含一个新工件：paging-testing。此工件提供了旨在独立单元测试应用的每一层及其与 Paging 集成的 API。

例如，此第一个版本包含一个 TestPager 类，可让您独立于通常需要模拟端到端 Paging 集成的 Pager 和真实 UI 验证您自己的自定义 PagingSource 实现的行为。

TestPager 应被视为一个假体 (fake) - 一种测试替身 (test double)，它镜像了 Pager 的真实实现，同时提供了一个简化的 API 表面来测试 PagingSource。这些 API 是 suspend API，应在 runTest 中运行，如在 Android 上测试 Kotlin 协程指南中所述。

在 room-paging 测试中可以找到使用这些 API 的示例，这些测试已重构为使用 TestPager。

API 变更

• 通过 LoadResult.Page.iterator() 方便地迭代 LoadResult.Page.data。当给定一个 List<LoadResult.Page> 时，例如传递给 PagingSource.getRefreshKey 方法的 PagingState 的 pages 属性，这间接允许使用 Kotlin 标准库 flatten 方法。(Ie0718)

版本 3.2.0-alpha02

2022 年 8 月 10 日

androidx.paging:paging-*:3.2.0-alpha02 发布。版本 3.2.0-alpha02 包含这些提交。

新功能

• Paging 现在通过 AsyncPagingDataDiffer 或 PagingDataAdapter 类提供日志，以公开从 PagingData 收集的调试信息。
• 可以通过 adb shell 命令 adb shell setprop log.tag.Paging [DEBUG|VERBOSE]. 启用日志。(b/235527159)

bug 修复

• 修复了使用 paging-common:3.2.0-alpha01 和运行时 paging-runtime:3.1.1 或更早版本时缺少 PagingDataDiffer 构造函数错误的问题。(b/235256201)

版本 3.2.0-alpha01

2022 年 6 月 1 日

androidx.paging:paging-*:3.2.0-alpha01 发布。版本 3.2.0-alpha01 包含这些提交。

API 变更

• 添加了接受 CoroutineContext 而非 CoroutineDispatcher 的 PagingDataAdapter 和 AsyncPagingDataDiffer 构造函数。(Idc878)
• 默认情况下，PagingData.from() 和 PagingData.empty() 将不再影响 presenter 端的 CombinedLoadStates。已添加一个新重载，允许将 sourceLoadStates 和 remoteLoadStates 传递给这些构造函数，以保持将 LoadStates 完全设置为终端状态（即 NotLoading(endOfPaginationReached = false)）的现有行为，并且可以选择包含 remote states（如果需要）。如果未传递 LoadStates，则当 presenter 接收到静态 PagingData 时，将保持先前的 CombinedLoadStates。(Ic3ce5, b/205344028)

bug 修复

• 在 PagingSource.getRefreshKey() 返回 null 但设置了非 null initialKey 的情况下，PagingSource.getRefreshKey() 的结果现在被正确优先考虑。(Ic9542, b/230391606)

外部贡献

• 由于 test-coroutines-lib 迁移，更新了 :compose:ui:ui-test api (updateApi) (I3366d)

版本 3.1

版本 3.1.1

2022 年 3 月 9 日

androidx.paging:paging-*:3.1.1 发布。版本 3.1.1 包含这些提交。

bug 修复

• 移除了由 .cachedIn() 错误插入的代与代之间的中间 LoadState.NotLoading 事件。此变更通过移除重试失败加载、刷新或失效之间产生的冗余 LoadState.NotLoading 事件，使得对 LoadState 变更的响应变得更加容易。

版本 3.1.0

2021 年 11 月 17 日

androidx.paging:paging-*:3.1.0 发布。版本 3.1.0 包含这些提交。

自 3.0.0 以来的重要变更

• Flow<PagingData>.observable 和 Flow<PagingData>.flowable API 不再是实验性的
• LoadState 的行为变更
  • 对于 PagingSource 和 RemoteMediator，endOfPaginationReached 现在对于 LoadType.REFRESH 始终为 false
  • Paging 中的 LoadStates 现在会等待 PagingSource 和 RemoteMediator 返回有效值后才向下游发送。新一代 PagingData 现在将始终以 Loading 作为刷新状态开始，而不是在某些情况下错误地重置为 NotLoading。
  • presenter API 上的 .loadStateFlow 和 .addLoadStateListener 不再重复发送初始 CombinedLoadStates，该初始状态的 mediator states 始终设置为 null
• 现在，旧一代的取消操作会在失效/新一代时立即发生。不再需要对 Flow<PagingData> 使用 .collectLatest，尽管仍然建议这样做。
• 添加了 PagingSource.LoadResult.Invalid 作为 PagingSource.load 的新返回类型，这会导致 Paging 丢弃对该 PagingSource 的任何待处理或未来的加载请求，并使其失效。此返回类型旨在处理可能从数据库或网络返回的无效或过时数据。
• 添加了 .onPagesPresented 和 .addOnPagesUpdatedListener presenter API，这些 API 在 UI 中显示页面更新时同步触发。页面更新可能发生在以下情况：
  • 新一代 PagingData 的初始加载完成，无论新一代是否包含对显示项目的任何更改。即，即使新一代完成初始加载后列表完全相同，没有更新，此回调仍会触发。
  • 插入了一个页面，即使插入的页面不包含任何新项目。
  • 丢弃了一个页面，即使丢弃的页面是空的。

版本 3.1.0-rc01

2021 年 11 月 3 日

androidx.paging:paging-*:3.1.0-rc01 发布。版本 3.1.0-rc01 包含这些提交。

bug 修复

• 修复了在没有观察者或观察者切换到新 PagingData 之间，Paging 向下游发送多个加载事件时，.cachedIn() 中的竞争条件和内存泄漏问题。(aosp/1869943)

版本 3.1.0-beta01

2021 年 10 月 13 日

androidx.paging:paging-*:3.1.0-beta01 发布。版本 3.1.0-beta01 包含这些提交。

bug 修复

• 修复了许多快速项目访问可能导致它们在 prefetchDistance 中被丢弃的问题，从而导致页面加载停滞。当许多项目以优先加载用户滚动方向的方式布局时，这个问题尤其严重。这些项目访问现在被缓冲并同步优先处理，以防止它们被丢弃。(aosp/1833273)

版本 3.1.0-alpha04

2021 年 9 月 29 日

androidx.paging:paging-*:3.1.0-alpha04 发布。版本 3.1.0-alpha04 包含这些提交。

API 变更

• Flow<PagingData>.observable 和 Flow<PagingData>.flowable API 不再是实验性的。(Ie0bdd)

bug 修复

• 对于 LoadStates，对于 LoadType.REFRESH，endOfPaginationReached 现在始终为 false。以前，对于 RemoteMediator REFRESH，endOfPaginationReached 可能为 true，但对于 PagingSource 则不行。此行为现已统一为始终返回 false，因为 REFRESH 永远不应是终端状态，并且现在已作为 API 合同的一部分在 LoadStates 中进行记录。在决定分页是否终止时，应始终参考 APPEND 或 PREPEND 方向。(I047b6)

• Paging 中的 LoadStates 现在会在代与代之间等待 PagingSource 和 RemoteMediator 返回有效值后才向下游发送。这可以防止新一代 PagingData 在 CombinedLoadStates.source.refresh 已经处于 Loading 状态时发送 NotLoading；新一代 PagingData 现在将始终以 Loading 作为刷新状态开始，而不是在某些情况下错误地先重置为 NotLoading。

  现在，旧一代的取消操作会在失效/新一代时立即发生。不再需要对 Flow<PagingData> 使用 .collectLatest，尽管仍然强烈建议这样做。(I0b2b5, b/177351336, b/195028524)

• presenter API 上的 .loadStateFlow 和 .addLoadStateListener 不再重复发送初始 CombinedLoadStates，该初始状态的 mediator states 始终设置为 null，source states 始终设置为 NotLoading(endOfPaginationReached = false)。这意味着

  1. 如果您使用 RemoteMediator，mediator states 将始终填充数据。
  2. 注册新的 loadState 监听器或在 .loadStateFlow 上注册新的 collector 不会再立即发送当前值，如果它还没有从 PagingData 收到真实的 CombinedLoadStates。这可能发生在 collector 或监听器在 PagingData 提交之前启动的情况下。(I1a748)

版本 3.1.0-alpha03

2021 年 7 月 21 日

androidx.paging:paging-*:3.1.0-alpha03 发布。版本 3.1.0-alpha03 包含这些提交。

API 变更

• 向 PagingSource 添加了第三种 LoadResult 返回类型 LoadResult.Invalid。当 PagingSource.load 返回 LoadResult.Invalid 时，paging 将丢弃加载的数据并使 PagingSource 失效。此返回类型旨在处理可能从数据库或网络返回的无效或过时数据。

  例如，如果底层数据库被写入，但 PagingSource 未及时失效，则如果其实现依赖于其加载的基础数据集的不可变性（例如，LIMIT OFFSET 风格的数据库实现），它可能会返回不一致的结果。在这种情况下，建议在加载后检查失效，并返回 LoadResult.Invalid，这会导致 Paging 丢弃对该 PagingSource 的任何待处理或未来的加载请求，并使其失效。

  Paging2 API 也支持此返回类型，该 API 利用 LivePagedList 或 RxPagedList。当将 PagingSource 与 Paging2 的 PagedList API 一起使用时，PagedList 会立即分离，停止进一步尝试在此 PagedList 上加载数据，并触发 PagingSource 的失效。

  LoadResult 是一个 sealed class，这意味着这是一个源不兼容的更改，直接使用 PagingSource.load 结果的用例必须在编译时处理 LoadResult.Invalid。例如，使用 exhaustive-when 检查返回类型的 Kotlin 用户必须添加对 Invalid 类型的检查。(Id6bd3, b/191806126, b/192013267)

bug 修复

• 通过 PagingSource.registerInvalidatedCallback 或 DataSource.addInvalidatedCallback 添加的失效回调现在会在它们在已失效的 PagingSource / DataSource 上注册时自动触发。这解决了当提供的 Source 在初始加载期间已经失效时导致 Paging 丢弃失效信号并卡住的竞争条件问题。此外，失效回调在触发后会被正确移除，因为它们保证最多被调用一次。(I27e69)
• 从新 instanced 的 PagedList 流提交占位符初始值 (InitialPagedList)，例如 LivePagedListBuilder 或 RxPagedListBuilder，将不再清除先前加载的数据。

版本 3.1.0-alpha02

2021 年 7 月 1 日

androidx.paging:paging-*:3.1.0-alpha02 发布。版本 3.1.0-alpha02 包含这些提交。

新功能

• 添加了 onPagesPresented 监听器和 flow presenter API，这些 API 在 UI 中更新显示的页面后立即触发。

  由于这些更新与 UI 同步，您可以调用 adapter 方法（例如 .snapshot、.getItemCount）以在应用更新后检查状态。请注意，.snapshot() 被留待显式调用，因为它在每次更新时都可能很昂贵。

  页面更新可能发生在以下情况

  • 新一代 PagingData 的初始加载完成，无论新一代是否包含对显示项目的任何更改。即，即使新一代完成初始加载后列表完全相同，没有更新，此回调仍会触发。
  • 插入了一个页面，即使插入的页面不包含任何新项目
  • 丢弃了一个页面，即使丢弃的页面是空的 (I272c9, b/189999634)

bug 修复

• 从 LivePagedList 或 RxPagedList 产生的初始值访问 PagedList.dataSource 将不再错误地抛出 IllegalStateException (I96707)

版本 3.1.0-alpha01

2021 年 6 月 2 日

androidx.paging:paging-*:3.1.0-alpha01 发布。版本 3.1.0-alpha01 包含这些提交。

API 变更

• paging-rxjava3 提供的类现在位于 androidx.paging.rxjava3 包下，以免与 paging-rxjava2 冲突 (Ifa7f6)

bug 修复

• 修复了 Paging 有时会向 RecyclerView 发送 no-op differ 事件的问题，这可能导致某些监听器提前触发。(Ic507f, b/182510751)

外部贡献

• 向 rxjava3 工件添加了已废弃的 PagedList compat API (Id1ce2, b/182497591)

Paging Compose 版本 1.0.0

版本 1.0.0-alpha20

2023 年 5 月 24 日

androidx.paging:paging-compose:1.0.0-alpha20 发布。版本 1.0.0-alpha20 包含这些提交。

新功能

• Paging Compose 现在支持通过创建 PagingData.from(fakeData) 并将该 PagingData 封装在 MutableStateFlow 中（例如 MutableStateFlow(PagingData.from(listOf(1, 2, 3)))）来预览虚假数据列表。通过使用该数据作为 @Preview 的输入，调用 collectAsLazyPagingItems() 将提供可预览的 LazyPagingItems。(I8a78d, b/194544557)

bug 修复

• 从 pager.flow.cachedIn 缓存的数据（已在 LazyPagingItems 中收集）现在将在状态恢复后立即可用，无需异步收集。这意味着缓存的数据将在状态恢复后立即在初始组合时准备好显示。(I97a60, b/177245496)

版本 1.0.0-alpha19

2023 年 5 月 3 日

androidx.paging:paging-compose:1.0.0-alpha19 发布。版本 1.0.0-alpha19 包含这些提交。

支持所有 lazy 布局

以前，Paging Compose 在 LazyListScope 上提供了自定义的 items 和 itemsIndexed 扩展，这意味着您无法将 Paging Compose 与其他 lazy 布局一起使用，例如 LazyVerticalGrid、HorizontalPager 或 Wear 和 TV 库提供的其他自定义 lazy 组件。解决这种不灵活性是此版本的主要更新。

为了支持更多 lazy 布局，我们需要在不同的层构建 API - Paging Compose 现在在 LazyPagingItems 上提供了稍微更底层的扩展方法 itemKey 和 itemContentType，而不是为每个 lazy 布局提供自定义的 items API。这些 API 专注于帮助您实现 key 和 contentType 参数，这些参数已存在于 LazyColumn、LazyVerticalGrid 以及 HorizontalPager 等 API 的标准 items API 中。(Ifa13b, Ib04f0, b/259385813)

这意味着支持 LazyVerticalGrid 看起来像这样

// This part is unchanged
val lazyPagingItems = pager.collectAsLazyPagingItems()

LazyVerticalGrid(columns = GridCells.Fixed(2)) {
  // Here we use the standard items API
  items(
    count = lazyPagingItems.itemCount,
    // Here we use the new itemKey extension on LazyPagingItems to
    // handle placeholders automatically, ensuring you only need to provide
    // keys for real items
    key = lazyPagingItems.itemKey { it.uniqueId },
    // Similarly, itemContentType lets you set a custom content type for each item
    contentType = lazyPagingItems.itemContentType { "contentType" }
  ) { index ->
    // As the standard items call provides only the index, we get the item
    // directly from our lazyPagingItems
    val item = lazyPagingItems[index]
    PagingItem(item = item)
  }
}

有关使用这些新 API 的更多示例，请参阅我们的示例。

虽然这些更改确实使 LazyColumn 和 LazyRow 示例的行数略有增加，但我们认为对于将来使用 Paging Compose 的用户来说，所有 lazy 布局之间的一致性是一个重要因素。因此，现在已废弃现有的 LazyListScope 扩展。(I0c459, I92c8f, b/276989796)

API 变更

• 为了简化向新 API 的迁移，LazyListScope 上的 items 和 itemsIndexed 扩展函数现在支持 contentType 参数，这与新 API 中的支持相对应。(Ib1918, b/255283378)

依赖项更新

• Paging Compose 已将其依赖项从 Compose 1.0.5 更新到 Compose 1.2.1。(Ib1918, b/255283378)

版本 1.0.0-alpha18

2023 年 2 月 8 日

androidx.paging:paging-compose:1.0.0-alpha18 发布，无任何变更。版本 1.0.0-alpha18 包含这些提交。

版本 1.0.0-alpha17

2022 年 10 月 24 日

androidx.paging:paging-compose:1.0.0-alpha17 发布。版本 1.0.0-alpha17 包含这些提交。

新功能

• 在调用 collectLazyPagingItems 时添加了对自定义 CoroutineContext 的支持。(I7a574, b/243182795, b/233783862)

版本 1.0.0-alpha16

2022 年 8 月 10 日

androidx.paging:paging-compose:1.0.0-alpha16 发布。版本 1.0.0-alpha16 包含这些提交。

新功能

• Paging 现在通过 LazyPagingItems 类提供日志，以公开从 PagingData 收集的调试信息。
• 可以通过 adb shell 命令 adb shell setprop log.tag.Paging [DEBUG|VERBOSE] 启用日志。([b/235527159}(https://issuetracker.google.com/issues/235527159))

bug 修复

• 修复了使用 paging-compose:1.0.0-alpha15 和 paging-common:3.1.1 或更早版本时缺少 PagingDataDiffer 构造函数错误的问题。(b/235256201,b/239868768)

版本 1.0.0-alpha15

2022 年 6 月 1 日

androidx.paging:paging-compose:1.0.0-alpha15 发布。版本 1.0.0-alpha15 包含这些提交。

API 变更

• 添加了接受 CoroutineContext 而非 CoroutineDispatcher 的 PagingDataAdapter 和 AsyncPagingDataDiffer 构造函数。(Idc878)

bug 修复

• LazyPagingItems 现在将初始 loadState 设置为具有 LoadState.Loading 刷新。(I55043, b/224855902)

版本 1.0.0-alpha14

2021 年 10 月 13 日

androidx.paging:paging-compose:1.0.0-alpha14 发布。版本 1.0.0-alpha14 包含这些提交。

版本 1.0.0-alpha13

2021 年 9 月 29 日

androidx.paging:paging-compose:1.0.0-alpha13 发布。版本 1.0.0-alpha13 包含这些提交。

API 变更

• LazyPagingItems.snapshot() 函数被 LazyPagingItems.itemSnapshotList 属性替换 (Ie2da8)
• 已废弃的 LazyPagingItems.getAsState() 已移除 (Ie65e4)

版本 1.0.0-alpha12

2021 年 7 月 21 日

androidx.paging:paging-compose:1.0.0-alpha12 发布。版本 1.0.0-alpha12 包含这些提交。

API 变更

• 用于将 Paging 与 LazyColumn/Row 连接的 items(lazyPagingItems) 和 itemsIndexed(lazyPagingItems) 现在接受可选的 key 参数，允许您指定表示该项目的稳定 key。您可以在此处详细了解 key。(I7986d)
• 函数 lazyPagingItems.getAsState(index) 现已废弃。请改用 lazyPagingItems[index]。(I086cb, b/187339372)

版本 1.0.0-alpha11

2021 年 6 月 30 日

androidx.paging:paging-compose:1.0.0-alpha11 发布。版本 1.0.0-alpha11 包含以下提交。

版本 1.0.0-alpha10

2021 年 6 月 2 日

androidx.paging:paging-compose:1.0.0-alpha10 发布。版本 1.0.0-alpha10 包含以下提交。

版本 1.0.0-alpha09

2021 年 5 月 18 日

androidx.paging:paging-compose:1.0.0-alpha09 发布。版本 1.0.0-alpha09 包含以下提交。

bug 修复

• LazyPagingItems 的 itemCount 和 item getter 现在是可观测的，这也使其能够与 LazyVerticalGrid 一起使用 (Ie2446, b/171872064, b/168285687)

Compose 兼容性

• androidx.paging:paging-compose:1.0.0-alpha09 仅与 Compose 版本 1.0.0-beta07 及更高版本兼容。

版本 1.0.0-alpha08

2021 年 2 月 24 日

androidx.paging:paging-compose:1.0.0-alpha08 发布。版本 1.0.0-alpha08 包含以下提交。

更新以集成 Compose 1.0.0-beta01。

版本 1.0.0-alpha07

2021 年 2 月 10 日

androidx.paging:paging-compose:1.0.0-alpha07 发布。版本 1.0.0-alpha07 包含以下提交。

更新以集成 Compose alpha12。

版本 1.0.0-alpha06

2021 年 1 月 28 日

androidx.paging:paging-compose:1.0.0-alpha06 发布。版本 1.0.0-alpha06 包含以下提交。

bug 修复

更新以依赖 Compose 1.0.0-alpha11。

版本 1.0.0-alpha05

2021 年 1 月 13 日

androidx.paging:paging-compose:1.0.0-alpha05 发布。版本 1.0.0-alpha05 包含以下提交。

更新以依赖 Compose 1.0.0-alpha10。

版本 1.0.0-alpha04

2020 年 12 月 16 日

androidx.paging:paging-compose:1.0.0-alpha04 发布。版本 1.0.0-alpha04 包含以下提交。

bug 修复

• 更新了便捷属性 CombinedLoadStates.refresh、CombinedLoadStates.prepend、CombinedLoadStates.append，使其仅在中介和来源加载状态均为 NotLoading 后从 Loading 过渡到 NotLoading，以确保远程更新已应用。(I65619)

版本 1.0.0-alpha03

2020 年 12 月 2 日

androidx.paging:paging-compose:1.0.0-alpha03 发布。版本 1.0.0-alpha03 包含以下提交。

• 更新以匹配 Compose 1.0.0-alpha08。

版本 1.0.0-alpha02

2020 年 11 月 11 日

androidx.paging:paging-compose:1.0.0-alpha02 发布。版本 1.0.0-alpha02 包含以下提交。

API 变更

• 向 LazyPagingItems 添加了 .peek()、.snapshot()、.retry() 和 .refresh() 方法，这些方法公开了与 AsyncPagingDataDiffer / PagingDataAdapter 中相同的功能 (Iddfe8, b/172041660)

版本 1.0.0-alpha01

2020 年 10 月 28 日

androidx.paging:paging-compose:1.0.0-alpha01 发布。版本 1.0.0-alpha01 包含以下提交。

新功能

paging-compose 工件提供了 Paging Library 与 Jetpack Compose 之间的集成。一个简单的用法示例

  @Composable
  @OptIn(ExperimentalLazyDsl::class)
  fun ItemsDemo(flow: Flow<PagingData<String>>) {
      val lazyPagingItems = flow.collectAsLazyPagingItems()
      LazyColumn {
          items(lazyPagingItems) {
              Text("Item is $it")
          }
      }
  }

版本 3.0.1

版本 3.0.1

2021 年 7 月 21 日

androidx.paging:paging-*:3.0.1 发布。版本 3.0.1 包含以下提交。

bug 修复

• 从 LivePagedList 或 RxPagedList 生成的初始值中访问 PagedList.dataSource 将不再错误地抛出 IllegalStateException (I96707)

版本 3.0.0

版本 3.0.0

2021 年 5 月 5 日

androidx.paging:paging-*:3.0.0 发布。版本 3.0.0 包含以下提交。

3.0.0 的主要功能

Paging 2.x.x 中的大部分现有 API 已弃用，取而代之的是新的 Paging 3 API，带来了以下改进

• 对 Kotlin 协程和 Flow 的一流支持
• 支持取消
• 内置加载状态和错误信号
• 重试 + 刷新功能
• 所有三个 DataSource 子类已合并为一个统一的 PagingSource 类
• 自定义页面转换，包括用于添加分隔符的内置转换
• 加载状态页眉和页脚

版本 3.0.0-rc01

2021 年 4 月 21 日

androidx.paging:paging-*:3.0.0-rc01 发布。版本 3.0.0-rc01 包含以下提交。

bug 修复

• 修复了 Paging 有时会向 RecyclerView 发送 no-op differ 事件的问题，这可能导致某些监听器提前触发。(Ic507f, b/182510751)

版本 3.0.0-beta03

2021 年 3 月 24 日

androidx.paging:paging-*:3.0.0-beta03 发布。版本 3.0.0-beta03 包含以下提交。

bug 修复

• 我们改进了列表重新加载时处理占位符的方式，以防止 RecyclerView 中出现意外跳转。详情请参阅 NullPaddedDiffing.md。(If1490, b/170027529, b/177338149)
• 各种 PagedList 构建器（旧兼容路径）在调用 .build() 时不再错误地在主线程上同步调用 DataSource.Factory.create()。(b/182798948)

版本 3.0.0-beta02

2021 年 3 月 10 日

androidx.paging:paging-*:3.0.0-beta02 发布。版本 3.0.0-beta02 包含以下提交。

API 变更

• Rx3 扩展现在正确传播了 @ExperimentalCoroutinesApi 的 Opt-In 要求。以前它们被标记在 @get 方法上，由于 https://youtrack.jetbrains.com/issue/KT-45227，Kotlin 编译器会忽略该标记 (I5733c)

bug 修复

• 对实验性 API 的公共使用强制执行限制 (I6aa29, b/174531520)
• 修复了在调用远程刷新时导致 PagingState 始终为 null 的错误。
• 修复了 PagingSource 返回空页面可能会阻止 Paging 再次获取以满足 prefetchDistance，导致 Paging “卡住” 的错误。

版本 3.0.0-beta01

2021 年 2 月 10 日

androidx.paging:paging-*:3.0.0-beta01 发布。版本 3.0.0-beta01 包含以下提交。

API 变更

• Rx2 和 Rx3 包装器现在公开了它们所依赖的实验性注解。如果您在 paging-rxjava2 或 paging-rxjava3 中使用 Rx 兼容包装器，现在需要使用 @OptIn(ExperimentalCoroutinesApi::class) 注解来标注用法 (Ib1f9d)

bug 修复

• 修复了通过兼容路径使用 v2 DataSource API 时有时会抛出的 IndexOutOfBoundsException: Inconsistency detected 错误
• 通过兼容路径使用 DataSource 时，在初始化期间调用 isInvalid 现在会正确地在 fetchDispatcher 而非主线程上启动。这修复了在使用 Room 的 PagingSource 实现时因在主线程上访问数据库而导致的 IllegalStateException 错误。

版本 3.0.0-alpha13

2021 年 1 月 27 日

androidx.paging:paging-*:3.0.0-alpha13 发布。版本 3.0.0-alpha13 包含以下提交。

API 变更

• PagingSource.getRefreshKey 不再是可选实现，它现在是没有默认实现的抽象函数。迁移用户可以继续返回默认实现（简单返回 null），但 getRefreshKey() 应该有一个真实的实现，返回一个基于用户当前滚动位置的键，如果可能，该键允许 Paging 通过 PagingState.anchorPosition 继续围绕视口中心加载。(I4339a)
• InvalidatingPagingSourceFactory 现在是一个最终类 (Ia3b0a)
• 允许通过附加的可选 SeparatorType 参数配置末端分隔符（页眉/页脚）行为。两个选项是
  • FULLY_COMPLETE - 现有行为；在添加末端分隔符之前，等待 PagingSource 和 RemoteMediator 都标记 endOfPaginationReached。如果未使用 RemoteMediator，则忽略远程 loadState。这主要用于当您只想在部分完全加载（包括从远程来源（例如网络）获取）时显示部分分隔符的情况。
  • SOURCE_COMPLETE - 即使使用 RemoteMediator，也仅等待 PagingSource 标记 endOfPaginationReached。这使得页眉和页脚可以与初始加载同步呈现，避免用户需要滚动才能看到末端分隔符。(Ibe993, b/174700218)

bug 修复

• 修复了一个罕见的内存泄漏问题，该问题发生在 PagingSource 在 PageFetcher 开始从中加载之前就失效时。(I9606b, b/174625633)

版本 3.0.0-alpha12

2021 年 1 月 13 日

androidx.paging:paging-*:3.0.0-alpha12 发布。版本 3.0.0-alpha12 包含以下提交。

API 变更

• InvalidatingPagingSourceFactory 不再是抽象类，因为它从未有任何抽象方法。(I4a8c4)
• 为 Java 用户添加了接受 ViewModel 而非 Lifecycle 或 CoroutineScope 的 .cachedIn() 重载。(I97d81, b/175332619)
• 允许 Java 调用者以异步方式使用 PagingData 转换操作，通过在转换操作符参数中接受一个 Executor。所有带有 -Sync 后缀的转换操作符现已移除 -Sync 后缀，而 Kotlin 协程用户需要通过调用接受挂起块的扩展函数来消除歧义。所有 PagingData 转换操作符已移至静态类 PagingDataTransforms 下的扩展函数。Java 用户需要通过静态帮助器调用它们，例如 PagingDataTransforms.map(pagingData, transform)。对于 Kotlin 用户，语法相同，但需要导入函数。(If6885, b/172895919)

bug 修复

• 修复了在 adapter.refresh() 期间，如果已达到分页末尾，则 RemoteMediator.load() 不会被调用的错误。

版本 3.0.0-alpha11

2020 年 12 月 16 日

androidx.paging:paging-*:3.0.0-alpha11 发布。版本 3.0.0-alpha11 包含以下提交。

新功能

• 对以下基本用例添加了保存状态支持（完整支持，尤其是在分层源情况下仍在进行中）
  • flow 已缓存且应用程序未终止（例如，flow 缓存到 view model 中，且 Activity 在进程中重建）
  • 分页源已计数，占位符已启用，且布局不是交错的。

API 变更

• PagingSource.getRefreshKey() 现在是稳定 API (I22f6f, b/173530980)
• PagingSource.invalidate 不再是开放函数。如果需要在失效发生时收到通知，请考虑调用 registerInvalidatedCallback 方法而不是覆盖 invalidate。(I628d9, b/173029013, b/137971356)
• Pager 现在除了常规构造函数外，还有一个实验性构造函数，避免通过 opt-in 注解将实验性 API 泄露到非实验性公共 API 中。(I9dc61, b/174531520)
• 更新了便捷属性 CombinedLoadStates.refresh、CombinedLoadStates.prepend、CombinedLoadStates.append，使其仅在中介和来源加载状态均为 NotLoading 后从 Loading 过渡到 NotLoading，以确保远程更新已应用。(I65619)

• LoadParams.pageSize 已移除（已弃用）。建议在 PagingSource 中使用 LoadParams.loadSize。

  LoadParams.loadSize 总是等于 PagingConfig.pageSize，除了初始加载调用时，它等于 PagingConfig.initialLoadSize。

  如果您在不使用 Pager 或 PagedList 的情况下测试 Paging2 DataSource，并且同时设置了 initialLoadSize，则 pageSize 可能与 PagingConfig.pageSize 不匹配。如果这对您的测试很重要，请尝试使用 Pager/PagedList，它会在内部为您的 DataSource 加载方法设置正确的 PageSize。(I98ac7, b/149157296)

bug 修复

• 修复了在使用分隔符并设置 PagingConfig.maxSize 时因 IllegalStateException 导致的崩溃。(I0ed33, b/174787528)
• 修复了在使用 RemoteMediator 时，如果设置了 RemoteMediator，则 PREPEND / APPEND 的加载状态不会在初始加载后立即更新为 NotLoading(endOfPaginationReached = true) 的错误。(I8cf5a)
• 修复了 presenter 端的 API（例如 .snapshot()、.peek() 等）在 ListUpdateCallback 更新中返回先前（过期）列表的错误。
• 修复了与 RemoteMediator 一起使用时 Separators 操作符不会添加页眉或页脚的错误。
• 修复了 RemoteMediator 的 LoadState 更新到 NotLoading 时会卡在 Loading 状态的错误。
• 修复了 Paging2.0 兼容 API .asPagingSourceFactory() 可能导致底层 DataSource 在不正确的 CoroutineDispatcher 上初始化的问题。这解决了崩溃和可能的 ANR 情况，尤其是在使用 Room 当前的 PagingSource 实现（使用了此兼容路径）时。

版本 3.0.0-alpha10

2020 年 12 月 2 日

androidx.paging:paging-*:3.0.0-alpha10 发布。版本 3.0.0-alpha10 包含以下提交。

API 变更

• 已移除已弃用的 dataRefreshFlow 和 dataRefreshListener API，因为它们与 loadStateFlow / Listener 更新功能重复。对于正在迁移的用户，loadStateFlow 的等效用法是

  loadStateFlow.distinctUntilChangedBy { it.refresh }
      .filter { it.refresh is NotLoading }
  

  (Ib5570, b/173530908)

bug 修复

• RemoteMediator REFRESH 的 endOfPaginationReached 现在可以正确传播到 LoadState 更新，并防止远程 APPEND 和 PREPEND 触发。(I94a3f, b/155290248)
• 由于初始页面为空或大量过滤而显示空列表不再阻止 Paging 启动 PREPEND 或 APPEND 加载。(I3e702, b/168169730)
• 修复了在 PagingSource 快速失效时，后续代不会调用 getRefreshKey 的问题。(I45460, b/170027530)

外部贡献

• 添加了一个新的抽象类 InvalidatingPagingSourceFactory，该类具有 .invalidate() API，可将其发出的所有 PagingSource 的失效信号转发。感谢 @claraf3！(Ie71fc, b/160716447)

已知问题

• 使用 RemoteMediator 时，.insertSeparators() 转换生成的页眉和页脚可能不会立即显示 b/172254056
• 如果失效和 PagingSource.load(LoadParams.Refresh(...)) 在 RemoteMediator.load() 返回之前完成，使用 RemoteMediator 可能会导致远程 LoadState 卡住 b/173717820

版本 3.0.0-alpha09

2020 年 11 月 11 日

androidx.paging:paging-*:3.0.0-alpha09 发布。版本 3.0.0-alpha09 包含以下提交。

API 变更

• 使用 replaceWith 子句完全弃用 dataRefreshFlow / Listener 方法。(I6e2dd)

bug 修复

• 修复了在使用带有 RemoteMediator 的分隔符时，如果在返回 endOfPagination 的远程加载仍在运行时触发了失效，则会抛出 IllegalArgumentException 的问题。(I3a260)

版本 3.0.0-alpha08

2020 年 10 月 28 日

androidx.paging:paging-*:3.0.0-alpha08 发布。版本 3.0.0-alpha08 包含以下提交。

API 变更

• 通过在 Kotlin 中使用函数式接口启用 SAM 转换（在 Kotlin 1.4 中可用），Kotlin / Java 版本的 DataSource.InvalidatedCallback 已合并。这也修复了一个错误，即 Kotlin 版本的失效回调在通过 .map 或 .mapByPage 转换后未被调用。(I1f244, b/165313046)

bug 修复

• Paging 与 ViewPager 的交互已显著改善。具体来说，Paging 不会再因页面失效而取消 RemoteMediator#load 调用。此外，如果需要 REFRESH，在 REFRESH 请求成功完成之前，它也不会再发出 append/prepend 加载请求。(I6390b, b/162252536)
• 已为 androidx 启用 MissingGetterMatchingBuilder 的 API lint 检查 (I4bbea, b/138602561)
• 修复了 .withLoadState* ConcatAdapter 帮助器因从后台线程通知 RecyclerView 而导致崩溃的错误 (I18bb5, b/170988309)
• 修复了一个错误，即加载非常小的非空页面有时会阻止预取正确触发加载。Iffda3 b/169259468

版本 3.0.0-alpha07

2020 年 10 月 1 日

androidx.paging:paging-*:3.0.0-alpha07 发布。版本 3.0.0-alpha07 包含以下提交。

API 变更

• 基于 Guava 的 Async PagingData 操作符现在接受 Executor 作为参数，以控制执行上下文。(Id4372)

bug 修复

• 修复了 RemoteMediator 中因竞态条件导致的 IndexOutOfBounds 异常。(I00b7f, b/165821814)
• 修复了 DataSource -> PagingSource 转换中的竞态条件，该条件可能导致生成的 PagingSource 忽略来自 DataSource 的失效信号。
• 修复了页面获取逻辑中的一个问题，该问题有时会导致它无法获取新一代的 PagingSource，直到调用 PagingDataAdapter.refresh()。
• 修复了在使用转换为 PagingSource 的 DataSource（例如 Room 生成的 DataSource）并结合 RemoteMediator 时，有时会丢失滚动位置的问题。

外部贡献

• 感谢 @simonschiller 添加了基于 RxJava2、RxJava3 和 Guava 的 PagingData 异步转换操作符！

版本 3.0.0-alpha06

2020 年 9 月 2 日

androidx.paging:paging-*:3.0.0-alpha06 发布。版本 3.0.0-alpha06 包含以下提交。

API 变更

• 现在，每当调用 PagingDataAdapter.setHasStableIds 时，都会抛出 UnsupportedOperationException，并带有更清晰的消息，说明不支持稳定 ID。(Ib3890, b/158801427)

bug 修复

• insertSeparators 不再过滤掉空页面，即使插入了许多空页面，也允许 presenter 遵守预取距离。(I9cff6, b/162538908)

版本 3.0.0-alpha05

2020 年 8 月 19 日

androidx.paging:paging-*:3.0.0-alpha05 发布。版本 3.0.0-alpha05 包含以下提交。

bug 修复

• Paging 现在即使在显示数据被大量过滤的情况下也能正确预取页面
• 对重试加载返回 LoadResult.Error 不再导致 Item 访问错误地重新触发重试

外部贡献

• 感谢 Clara F 帮助清理了一些测试！(549612)

版本 3.0.0-alpha04

2020 年 8 月 5 日

androidx.paging:paging-*:3.0.0-alpha04 发布。版本 3.0.0-alpha04 包含以下提交。

API 变更

• 向 AsyncPagingDataDiffer 和 PagingDataAdapter 添加了 peek() API，允许在不触发页面加载的情况下访问呈现的数据。(I38898, b/159104197)
• 向 PagingDataAdapter 和 AsyncPagingDataDiffer 添加了 snapshot() API，允许在不触发页面获取的情况下检索呈现的条目。(I566b6, b/159104197)
• 添加了 PagingData.from(List<T>) 构造函数，允许呈现静态列表，可以与整体 PagingData 流结合使用，以在某些状态下显示静态列表，例如在初始 REFRESH 完成之前或仅用于测试转换。(Id134d)
• 弃用 dataRefresh Flow / Listener API，因为它们旨在在 REFRESH 上公开呈现的条目状态，但随着 loadState Flow / Listener 回调时序和 itemCount 属性的改进，它们是冗余的 (Ia19f3)
• 为 PagingSource 和 RemoteMediator 添加了 RxJava3 兼容包装器 (I49ef3, b/161480176)

bug 修复

• 通过 toPagingSourceFactory 帮助器转换为 PagingSource 的 PositionalDataSource，包括 Room 生成的 PagingSource，现在可以正确地标记自己以支持跳转。(I3e84c, b/162161201)
• 修复了一个错误，即使用 submitData 的同步变体有时会导致竞态条件，从而抛出 ClosedSendChannelException。(I4d702, b/160192222)

外部贡献

• 感谢 Zac Sweers 代表 Slack 添加了 RxJava3 兼容包装器！(I49ef3, b/161480176)

版本 3.0.0-alpha03

2020 年 7 月 22 日

androidx.paging:paging-*:3.0.0-alpha03 发布。版本 3.0.0-alpha03 包含以下提交。

API 变更

• PagingState 的构造函数现在是公共的，这应该使测试 getRefreshKey() 的实现更容易。(I8bf15)
• 隐藏了 DataSource kotlin map 函数变体，使其在 Java 中不可见，以解决原始变体和 kotlin 变体之间的歧义。(If7b23, b/161150011)
• 为 Kotlin 用户提供便利的冗余 API 已标记为 @JvmSynthetic (I56ae5)
• 为 LoadResult.Page 的构造函数添加了重载，该构造函数将 itemsBefore 和 itemsAfter 默认为 COUNT_UNDEFINED (I47849)
• 使现有 PagingData 操作符接受挂起方法，并为 Java 用户引入了新的非挂起操作符 mapSync、flatMapSync 和 filterSync。现有的转换方法已移至扩展函数，因此 Kotlin 用户现在需要导入它们。(I34239, b/159983232)

bug 修复

• Room（以及 PositionalDataSource）PagingSources 现在将把一个前导分隔符作为第一页的一部分显示出来，这样用户就不需要滚动来显示它。(I6f747, b/160257628)
• 占位符上的项目访问现在可以正确触发 PagingSource 加载，直到返回经过 PagingData.filter() 转换后满足请求索引的页面为止。(I95625, b/158763195)
• 修复了一个错误，即有时在 PagingSource 返回错误后滚动会阻止 PagingDataAdapter.retry() 重试。(I1084f, b/160194384)
• 修复了丢弃页面后访问项目时可能不会加载页面的问题，即使项目访问位于 prefetchDistance 范围内。(Ie95ae, b/160038730)
• 设置 PagingConfig.maxSize 在丢弃事件后不再启用占位符。(I2be29, b/159667766)

版本 3.0.0-alpha02

2020 年 6 月 24 日

androidx.paging:paging-*:3.0.0-alpha02 发布。版本 3.0.0-alpha02 包含以下提交。

API 变更

• 为 PagingConfig 的构造函数添加了具有常见默认值的重载。(I39c50, b/158576040)
• 为 PagingDataAdapter 和 AsyncPagingDataDiffer 的构造函数添加了具有常见默认值的重载。(Ie91f5, b/158576040)
• 适配器 API dataRefreshFlow 和 dataRefreshListener 现在传递一个布尔值来指示 PagingData 是否为空。(I6e37e, b/159054196)
• 为 RemoteMediator 添加了 RxJava 和 Guava API - RxRemoteMediator 和 ListenableFutureRemoteMediator
• 为 PagingState 添加了用于常见项目访问的帮助器，例如 isEmpty() 和 firstItemOrNull()。(I3b5b6, b/158892717)

bug 修复

• Pager 现在会在工厂中检查 PagingSource 是否被重用，以防止意外重用无效的 PagingSource，这之前会导致不明确的错误。I99809, b/158486430)
• RemoteMediator REFRESH 的失败不再阻止 PagingSource 加载。(I38b1b, b/158892717)
• 在调用 submitData 的挂起版本后调用 submitData 的非挂起版本，不再因多个 PagingData 上的并发收集而导致崩溃。(I26358, b/158048877)
• 修复了配置更改后可能发生的“不能从 pager 收集两次”异常。(I58bcc, b/158784811)

版本 3.0.0-alpha01

2020 年 6 月 10 日

androidx.paging:paging-*:3.0.0-alpha01 发布。版本 3.0.0-alpha01 包含以下提交。

Paging Library 已更新到 3.0 版本，以启用几项主要新功能。

3.0 版本的新功能

• 对 Kotlin 协程和 Flow 的一流支持。
• 支持使用协程挂起函数、RxJava Single 或 Guava ListenableFuture 原语进行异步加载。
• 用于响应式 UI 设计的内置加载状态和错误信号，包括重试和刷新功能。
• 存储库层的改进
  • 简化的数据源接口
  • 简化的网络 + 数据库分页
  • 支持取消
• 演示层的改进
  • 自定义页面转换
  • 列表分隔符
  • 加载状态页眉和页脚

已知问题

• Paging 3 的 javadoc 尚未发布。在此期间，请使用上方链接的指南或 Kotlin 文档。(b/158614050)

版本 2.1.2

版本 2.1.2

2020 年 3 月 18 日

androidx.paging:paging:2.1.2 发布。版本 2.1.2 包含相对于 2.1.0 的这些提交。

bug 修复

• 修复了在失效期间转换位置时，在极少数情况下出现的 IndexOutOfBoundsException。

发布问题

• Paging 版本 2.1.1 从配置错误的分支错误发布，暴露了部分实现的 API 和未来版本中的功能。

• Paging 2.1.2 包含了最初在 2.1.1 中发布的加载居中修复，但这次是正确地 cherry-picked 到 2.1.0 版本之上。如果您当前使用的是 2.1.1 版本，强烈建议升级到此版本。

版本 2.1.1

版本 2.1.1

2019 年 12 月 18 日

androidx.paging:paging-*:2.1.1 发布。版本 2.1.1 包含以下提交。

错误修复

• 当禁用占位符时，从 PositionalDataSources 的连续初始加载现在以最后访问为中心

版本 2.1.0

版本 2.1.0

2019 年 1 月 25 日

Paging 2.1.0 发布，与 2.1.0-rc01 无变化。

版本 2.1.0-rc01

2018 年 12 月 6 日

Paging 2.1.0-rc01 发布，与 2.1.0-beta01 无变化。

版本 2.1.0-beta01

2018 年 11 月 1 日

Paging 2.1.0-beta01 发布，与 2.1.0-alpha01 无变化。

版本 2.1.0-alpha01

2018 年 10 月 12 日

Paging 2.1.0-alpha01 有两项主要新增功能 - 页面丢弃，以及每个工件的 KTX 扩展库 - 以及其他一些 API 更改和错误修复。

API 变更

• 添加了 PagedList.Config.Builder.setMaxSize() 以限制内存中加载的项目数量。
• 添加了 androidx.paging.Config() 作为 PagedList.Config.Builder 的 Kotlin 替代方案
• 添加了 androidx.paging.PagedList() 作为 PagedList.Builder 的 Kotlin 替代方案
• 添加了 DataSourceFactory.toLiveData() 作为 LivePagedListBuilder 的 Kotlin 替代方案
• 添加了 DataSourceFactory.toObservable() 和 toFlowable() 作为 RxPagedListBuilder 的 Kotlin 替代方案
• 添加了 AsyncPagedListDiffer.addPagedListListener() 用于监听 PagedList 交换事件。b/111698609
• 添加了传递旧列表和新列表的 PagedListAdapter.onCurrentListChanged() 变体，并弃用了先前的变体。
• 添加了 PagedListAdapter/AsyncPagedListDiffer.submitList() 变体，该变体接受一个额外的回调，用于在 diff 处理后，分页列表显示时触发。这允许您将 PagedList 交换与其他 UI 更新同步。b/73781068
• 添加了 PagedList.getLoadedCount()，让您知道内存中有多少项目。请注意，如果禁用了占位符，返回值始终等于 .size()。

bug 修复

• 修复了在列表被重用时进行 diff 处理时出现的竞态条件 b/111591017
• 当索引无效时，PagedList.loadAround() 现在会抛出 IndexOutOfBoundsException。以前可能会因不明确的其他异常而崩溃。
• 修复了一种情况，即非常小的初始加载大小和未更改的数据会导致后续不再加载 b/113122599

版本 2.0.0

版本 2.0.0

2018 年 10 月 1 日

Paging 2.0.0 发布，包含一个错误修复。

bug 修复

• 修复了使用 PositionalDataSource 和占位符时，快速滚动可能导致的崩溃 b/114635383。

版本 2.0.0-beta01

2018 年 7 月 2 日

bug 修复

• 修复了在某些 prepend 情况（占位符禁用，PositionalDataSource）下内容消失的问题 b/80149146
• （已在 1.0.1 中发布）修复了 PagedListAdapter 和 AsyncPagedListDiffer 无法发出移动事件时崩溃的问题。b/110711937

Pre-AndroidX 依赖项

对于以下 Pre-AndroidX 版本的 Paging，请包含这些依赖项

dependencies {
    def paging_version = "1.0.0"

    implementation "android.arch.paging:runtime:$paging_version"

    // alternatively - without Android dependencies for testing
    testImplementation "android.arch.paging:common:$paging_version"

    // optional - RxJava support
    implementation "android.arch.paging:rxjava2:$paging_version"
}

版本 1.0.1

版本 1.0.1

2018 年 6 月 26 日

Paging 1.0.1 发布，包含运行时中的一个错误修复。强烈建议使用 1.0.1 以获得稳定性。Paging RxJava2 1.0.1 也已发布，与 1.0.0-rc1 相同。

bug 修复

• 修复了 PagedListAdapter 和 AsyncPagedListDiffer 无法发出移动事件时崩溃的问题。b/110711937

RxJava2 版本 1.0.0

RxJava2 版本 1.0.0-rc1

2018 年 5 月 16 日

Paging RxJava2 1.0.0-rc1 正式进入发布候选版本，与初始 alpha 版本无变化。

版本 1.0.0

版本 1.0.0-rc1

2018 年 4 月 19 日 Paging 发布候选版本

对于 Paging 1.0.0 版本，我们没有更多已知问题或计划中的新功能。请将您的项目升级到 1.0.0-rc1 版本，并帮助我们进行实战测试，以便我们发布一个坚如磐石的 1.0.0 版本。

此版本没有变化，与 1.0.0-beta1 相同。

版本 1.0.0-beta1

2018 年 4 月 5 日

Paging 将在短时间内进入 beta 版本，然后进入发布候选版本。Paging 1.0 不计划进行进一步的 API 更改，任何 API 更改的门槛都非常高。

Paging 的 Alpha RxJava2 支持作为一个单独的可选模块发布 (android.arch.paging:rxjava2:1.0.0-alpha1)，在稳定之前将暂时单独进行版本控制。

这个新库提供了 LivePagedListBuilder 的 RxJava2 替代方案，能够构建 Observables 和 Flowables，接受 Schedulers 而不是 Executors

val pagedItems = RxPagedListBuilder(myDataSource, /* page size */ 50)
        .setFetchScheduler(myNetworkScheduler)
        .buildObservable()

Observable<PagedList<Item>> pagedItems =
        RxPagedListBuilder(myDataSource, /* page size */ 50)
                .setFetchScheduler(myNetworkScheduler)
                .buildObservable();

新功能

• RxPagedListBuilder 通过新的 android.arch.paging:rxjava2 工件添加。

API 变更

• API 更改以阐明构建器中 executor 的作用

  • 将 setBackgroundThreadExecutor() 重命名为 setFetchExecutor()（在 PagedList.Builder 和 LivePagedListBuilder 中）

  • 将 setMainThreadExecutor() 重命名为 setNotifyExecutor()（在 PagedList.Builder 中）。

• 将 PagedList.mCallbacks 成员修复为私有。

bug 修复

• LivePagedListBuilder 在指定的 executor 上触发初始 PagedList 加载，而不是 Arch Components IO 线程池。

• 修复了内部 DataSource 包装器中的失效行为（用于实现 DataSource.map 以及禁用占位符的 PositionalDataSource 加载）b/77237534

版本 1.0.0-alpha7

2018 年 3 月 21 日

Paging 1.0.0-alpha7 与 Lifecycles 1.1.1 一同发布。由于 Paging alpha7 依赖于上述 Function 类的移动，您需要将您的 lifecycle:runtime 依赖项更新到 android.arch.lifecycle:runtime:1.1.1。

Paging alpha7 计划是 Paging 进入 beta 版本之前的最终版本。

API 变更

• DataSource.LoadParams 对象现在有了公共构造函数，并且 DataSource.LoadCallback 对象现在是抽象的。这使得可以包装 DataSource 或直接使用模拟回调测试 DataSource。b/72600421
• DataSource 和 DataSource.Factory 的映射器
  • map(Function<IN,OUT>) 允许您转换、包装或修饰 DataSource 加载的结果。
  • mapByPage(<List<IN>,List<OUT>>) 支持批量处理相同操作（例如，如果从 SQL 加载的项目需要额外查询单独的数据库，则可以作为批量操作完成）。
• 添加了 PagedList#getDataSource() 作为便捷方法 b/72611341
• 所有已弃用的类已从 API 中移除，包括 recyclerview.extensions 包的剩余部分和 LivePagedListProvider。
• DataSource.Factory 已从接口更改为抽象类，以启用 map 功能。

bug 修复

• 将 Builders 更改为 final。b/70848565
• Room DataSource 实现现在已修复以处理多表查询 - 此修复包含在 Room 1.1.0-beta1 中，请参阅上方。
• 修复了在 PositionalDataSource 中，如果启用了占位符且总大小恰好是页面大小的倍数，则 BoundaryCallback.onItemAtEndLoaded 不会调用的错误。

版本 1.0.0-alpha5

2018 年 1 月 22 日

bug 修复

• 修复了禁用占位符时页面加载的问题 b/70573345
• 新增日志用于追踪 IllegalArgumentException 错误 b/70360195（以及推测性的 Room 端修复）
• Javadoc 示例代码修复 b/70411933, b/71467637