分页

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

声明依赖项

要添加对分页的依赖项，您必须将 Google Maven 存储库添加到您的项目中。阅读 Google 的 Maven 存储库 以了解更多信息。

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

dependencies {
  def paging_version = "3.3.2"

  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.2"
}

dependencies {
  val paging_version = "3.3.2"

  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.2")
}

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

有关依赖项的更多信息，请参阅 添加构建依赖项。

反馈

您的反馈有助于使 Jetpack 变得更好。如果您发现新问题或有改进此库的想法，请告诉我们。在创建新问题之前，请查看此库中的 现有问题。您可以通过单击星形按钮对现有问题进行投票。

创建新问题

有关更多信息，请参阅 问题跟踪器文档。

版本 3.3

版本 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 包含 这些提交。

错误修复

• 修复了 AsyncPagingDataDiffer 或在其之上构建的 API（例如与 RecyclerView 一起使用的 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 之上，而不必需要内部 Paging API 或 paging-runtime 的 AsyncPagingDataDiffer。
• 在 LoadStates 和 CombinedLoadStates 中添加了新的 hasError 和 isIdle 辅助方法，分别用于检查 LoadStates 是否处于错误或 NotLoading 状态。还添加了一个新的 awaitNotLoading() Kotlin 扩展方法，用于 Flow<CombinedLoadStates>，该方法会等待，直到加载状态变为 NotLoading 或错误状态。
• PagingData.empty() 现在默认情况下会分派 NotLoading 状态，除非将自定义 LoadStates 传递给它的构造函数。这与现有行为不同，现有行为是在提交到 PagingDataAdapter 时不分派 LoadStates，或者在以 LazyPagingItems 形式收集时分派加载状态。在以 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 注释 @MainThread 注释。(I78f0d, b/327682438)

版本 3.3.0-alpha04

2024 年 3 月 6 日

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

错误修复

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

版本 3.3.0-alpha03

2024 年 2 月 7 日

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

新功能

• PagingDataPresenter 现在是一个公共类。多平台演示器现在可以构建在 PagingDataPresenter 之上，而不必需要内部 Paging API 或 paging-runtime 的 AsyncPagingDataDiffer。(Id1f74, b/315214786)
• 添加了新的 LoadStates 和 CombinedLoadStates 辅助方法，用于检查 LoadStates 是否处于错误或 NotLoading 状态。还添加了一个新的 API，该 API 会等待 LoadStateFlow，直到加载状态变为 NotLoading 或错误状态。(Id6c67)

行为变更

• PagingData.empty() 现在默认情况下会分派 NotLoading 状态，除非将自定义 LoadStates 传递给它的构造函数。这与现有行为不同，现有行为是在提交到 PagingDataAdapter 时不分派 LoadStates，或者在以 LazyPagingItems 形式收集时分派加载状态。在以 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)

外部贡献

• 感谢 CashApp 的 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 包含这些提交。

错误修复

• 修复了 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)))）来支持预览假数据列表。将此流传递到 @Preview 可组合项中，作为 collectAsLazyPagingItems() 的接收器以进行预览。
  • 支持所有懒惰布局，例如 LazyVerticalGrid 和 HorizontalPager，以及来自 Wear 和 TV 库的自定义懒惰组件。这是通过新的低级 LazyPagingItems 扩展方法 itemKey 和 itemContentType 实现的，这些方法可以帮助您实现 key 和 contentType 参数，以用于 LazyColumn、LazyVerticalGrid 以及 HorizontalPager 等 API 中的标准 items API。
  • items(lazyPagingItems) 和 itemsIndexed(lazyPagingItems) 仅支持 LazyListScope，已弃用。
• 新的 paging-testing 工件，提供围绕单独测试应用程序的每个层及其与 Paging 的集成而设计的 API。例如，它包括
  • TestPager 类，允许您独立于 Pager 和实际 UI 验证您自己的自定义 PagingSource 实现的行为。
  • ​​asPagingSourceFactory API，用于将 Flow<List<Value>> 或静态 List<Value> 转换为可传递给 Pager 进行测试的 PagingSourceFactory
  • asSnapshot 是 Flow<PagingData<Value>> 上的 Kotlin 扩展函数，它将 Flow<PagingData<Value>> 转换为直接的 List<Value>。 asSnapshot lambda 允许您通过 scrollTo 或 appendScrollWhile 等 API 模拟应用程序的 UI，以便您可以在分页数据集中验证数据快照在任何时间点是否正确。
• 添加了默认日志，以在两个级别公开分页调试信息：VERBOSE 和 DEBUG。可以通过命令 adb shell setprop log.tag.Paging [DEBUG|VERBOSE] 启用日志。这适用于带视图的分页和 Compose 的分页。
• 添加了 PagingDataAdapter 和 AsyncPagingDataDiffer 的构造函数，它们接受 CoroutineContext 而不是 CoroutineDispatcher。
• 添加了一个新的 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 包含以下提交。

分页 Compose

• 分页 Compose 已正式达到 API 稳定状态。因此，版本已从 1.0.0-alpha20 更新为与所有其他分页工件的版本一致。

API 变更

• 已从分页 Compose 中删除已弃用的 items(LazyPagingItems) 和 itemsIndexed(LazyPagingItems) API。有关其替换 API 的示例，请参阅 分页 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 分页测试。设置它不再对测试行为产生任何影响。 (Ie56ea)

版本 3.2.0-alpha05

2023 年 5 月 3 日

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

API 变更

• 现在，asSnapshot 的分页测试 API 将其 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 工件现在包含一个 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 调用被正确标记为只能在主线程上调用。 (I699b6)
• 从 TestPager 使用的泛型类型中删除了通配符，这使得在用 Java 编程语言编写的代码中更易于使用这些方法的结果。 (I56c42)

版本 3.2.0-alpha03

2022 年 10 月 24 日

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

分页测试

此版本包含一个新工件：paging-testing。此工件提供围绕独立测试应用程序的每一层及其与分页的集成而设计的 API。

例如，此第一个版本包含一个 TestPager 类，它允许您独立于 Pager 和实际 UI 验证您自己的自定义 PagingSource 实现的行为，而您通常需要模拟端到端分页集成。

TestPager 应被视为一个 **模拟** - 一个 测试替身，它反映了 Pager 的实际实现，同时为测试 PagingSource 提供简化的 API 表面。这些 API 是 suspend API，应在 runTest 中运行，如 在 Android 上测试 Kotlin 协程 指南中所述。

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

API 变更

• 通过 LoadResult.Page.iterator()，可以方便地迭代 LoadResult.Page.data。这间接允许使用 Kotlin 标准库 flatten 方法，当给定一个 List<LoadResult.Page> 时，比如 PagingState 的 pages 属性，它被传递给 PagingSource.getRefreshKey 方法。（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）

错误修复

• 修复了在使用 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 变更

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

错误修复

• 现在，在 PagingSource.getRefreshKey() 返回 null 的情况下，PagingSource.getRefreshKey() 的结果将正确地优先于 initialKey，但已设置了一个非 null 的 initialKey。（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 包含以下提交。

错误修复

• 删除了 .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。
  • 演示者 API 上的 .loadStateFlow 和 .addLoadStateListener 不再冗余地发送初始的 CombinedLoadStates，它始终具有设置为 null 的中介状态
• 在失效/新代时，对过去代的取消现在会急切地发生。它不再需要在 Flow<PagingData> 上使用 .collectLatest，尽管仍然建议这样做。
• PagingSource.LoadResult.Invalid 已被添加为来自 PagingSource.load 的新返回类型，这会导致 Paging 丢弃对该 PagingSource 的任何挂起的或将来的加载请求，并使它失效。此返回类型旨在处理可能从数据库或网络返回的无效或陈旧数据。
• 添加了 .onPagesPresented 和 .addOnPagesUpdatedListener 演示者 API，它们在页面在 UI 中呈现时同步触发。页面更新可能发生在以下场景中
  • 新一代 PagingData 的初始加载完成，无论新一代是否包含对呈现的项目的任何更改。例如，新一代完成初始加载且没有更新，因为列表完全相同，仍然会触发此回调。
  • 插入一个页面，即使插入的页面不包含新项目。
  • 删除一个页面，即使删除的页面是空的。

版本 3.1.0-rc01

2021 年 11 月 3 日

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

错误修复

• 修复了 .cachedIn() 中的竞争条件+内存泄漏，在 Paging 下游发送多个加载事件但没有观察者或观察者正在切换到新的 PagingData 之间时发生。（Ib682e）

版本 3.1.0-beta01

2021 年 10 月 13 日

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

错误修复

• 修复了一个问题，即许多快速项目访问会导致它们被丢弃，以供在 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）

错误修复

• 对于 LoadStates，endOfPaginationReached 现在始终为 LoadType.REFRESH 的 false。以前，endOfPaginationReached 可能为 RemoteMediator REFRESH 的 true，但对于 PagingSource 则不行。此行为现在已合并为始终返回 false，因为它对于 REFRESH 永远没有意义，并且现在已作为 LoadStates 中 API 合同的一部分进行记录。在决定分页是否终止时，你应该始终针对 APPEND 或 PREPEND 方向中的一个来进行决定。（I047b6）

• 来自 Paging 的 LoadStates 现在将在不同代之间发出下游之前等待来自 PagingSource 和 RemoteMediator 的有效值。这将防止新一代的 PagingData 在 CombinedLoadStates.source.refresh 中发送 NotLoading，如果它已经处于 Loading 状态；现在，新一代的 PagingData 将始终正确地以 Loading 开头，用于刷新状态，而不是在某些情况下首先错误地重置为 NotLoading。

  在失效/新代时，对过去代的取消现在会急切地发生。它不再需要在 Flow<PagingData> 上使用 .collectLatest，尽管仍然强烈建议这样做。（I0b2b5，b/177351336，b/195028524）

• .loadStateFlow 和 .addLoadStateListener 在演示者 API 上不再冗余地发送初始的 CombinedLoadStates，它始终具有设置为 null 的中介状态和设置为 NotLoading(endOfPaginationReached = false) 的源状态。这意味着

  1. 如果你使用 RemoteMediator，中介状态将始终填充。
  2. 在 .loadStateFlow 上注册新的 loadState 监听器或新的收集器将不再立即发出当前值，如果它没有从 PagingData 收到真实的 CombinedLoadStates。如果在提交 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 时，分页将丢弃加载的数据并使 PagingSource 失效。此返回类型旨在处理可能从数据库或网络返回的无效或陈旧数据。

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

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

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

错误修复

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

版本 3.1.0-alpha02

2021 年 7 月 1 日

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

新功能

• 添加了 onPagesPresented 监听器和流呈现器 API，这些 API 在 UI 中更新呈现的页面后立即触发。

  由于这些更新与 UI 同步，因此可以在更新应用后调用适配器方法，例如 .snapshot、.getItemCount，以检查状态。请注意，.snapshot() 必须显式调用，因为它在每次更新时执行可能会很昂贵。

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

  • 新一代 PagingData 的初始加载完成，无论新一代是否包含对呈现的项目的任何更改。例如，新一代完成初始加载且没有更新，因为列表完全相同，仍然会触发此回调。
  • 插入一个页面，即使插入的页面不包含新项目
  • 删除一个页面，即使删除的页面为空 (I272c9，b/189999634)

错误修复

• 从 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)

错误修复

• 修复了 Paging 有时会向 RecyclerView 发送空操作差异事件的问题，这可能会导致某些监听器过早触发。（Ic507f，b/182510751）

外部贡献

• 在 rxjava3 工件中添加了已弃用的 PagedList 兼容 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）

错误修复

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

版本 1.0.0-alpha19

2023 年 5 月 3 日

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

支持所有惰性布局

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

为了支持更多惰性布局，我们需要在不同的层级构建 API - 而不是为每个惰性布局提供自定义的 items API，Paging Compose 现在在 LazyPagingItems 中提供稍低级别的扩展方法 itemKey 和 itemContentType。这些 API 专注于帮助你实现 LazyColumn、LazyVerticalGrid 以及 HorizontalPager 等 API 中已存在的标准 items API 的 key 和 contentType 参数。（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 的人来说是一个重要因素。出于这个原因，对 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))

错误修复

• 修复了在使用 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 变更

• 为 PagingDataAdapter 和 AsyncPagingDataDiffer 添加了构造函数，它们接受 CoroutineContext 而不是 CoroutineDispatcher。（Idc878）

错误修复

• 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 变更

• items(lazyPagingItems) 和 itemsIndexed(lazyPagingItems) 用于将 Paging 连接到 LazyColumn/Row，现在接受可选的 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 包含这些提交。

错误修复

• LazyPagingItems 的 itemCount 和 item 获取器现在是可观察的，这使得它可以与 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 包含这些提交。

错误修复

更新为依赖于 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 包含这些提交。

错误修复

• 更新了便利属性，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 变更

• 在 LazyPagingItem 中添加了 .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 工件提供了 分页库 和 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 包含这些提交。

错误修复

• 从 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 的主要功能

分页 2.x.x 中的大多数现有 API 已经弃用，转而支持新的分页 3 API，以带来以下改进

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

版本 3.0.0-rc01

2021 年 4 月 21 日

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

错误修复

• 修复了 Paging 有时会向 RecyclerView 发送空操作差异事件的问题，这可能会导致某些监听器过早触发。（Ic507f，b/182510751）

版本 3.0.0-beta03

2021 年 3 月 24 日

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

错误修复

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

版本 3.0.0-beta02

2021 年 3 月 10 日

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

API 变更

• Rx3 扩展现在正确地传播了 @ExperimentalCoroutinesApi 的选择加入要求。之前它们标记在 @get 方法上，由于以下原因而被 Kotlin 编译器忽略：https://youtrack.jetbrains.com/issue/KT-45227 (I5733c)

错误修复

• 对实验性 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)

错误修复

• 修复了使用 v2 DataSource API 通过兼容性路径有时会抛出的 IndexOutOfBoundsException: Inconsistency detected 错误
• 使用兼容性路径时，DataSource 初始化期间的 isInvalid 调用现在会在 fetchDispatcher 上正确启动，而不是在主线程上启动。这修复了一个由于在主线程上访问 Db 导致的 IllegalStateException 错误，当时使用的是 Room 的 PagingSource 实现。

版本 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)

错误修复

• 修复了一个罕见的内存泄漏，该泄漏发生在 PageFetcher 甚至开始从 PagingSource 加载之前，PagingSource 就被失效了。 (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 用户添加了 .cachedIn() 的重载，它接受 ViewModel 而不是 Lifecycle 或 CoroutineScope。（I97d81，b/175332619）
• 允许 Java 调用者通过将 Executor 接受到转换运算符参数中以异步方式使用 PagingData 转换操作。现在所有 -Sync 转换运算符都已删除 -Sync 后缀，Kotlin Coroutine 用户需要通过调用接受挂起块的扩展函数来消除歧义。所有 PagingData 转换运算符已移至静态 PagingDataTransforms 类下的扩展。Java 用户需要通过静态辅助程序调用它们，例如：PagingDataTransforms.map(pagingData, transform) 对于 Kotlin 用户，语法相同，但您需要导入函数。（If6885，b/172895919）

错误修复

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

版本 3.0.0-alpha11

2020 年 12 月 16 日

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

新功能

• 已为以下基本用例添加了保存状态支持（完整支持，特别是在分层源情况下，仍在进行中）
  • 流被缓存且应用程序未被杀死（例如，流在视图模型中被缓存，并且活动在进程中被重新创建）
  • 分页源已计数，启用了占位符，并且布局未交错。

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）

错误修复

• 修复了在使用分隔符和 PagingConfig.maxSize 设置时，由于 IllegalStateException 导致的崩溃。（I0ed33，b/174787528）
• 修复了如果设置了 RemoteMediator，则 PREPEND/APPEND 的加载状态不会立即更新为 NotLoading(endOfPaginationReached = true) 的错误。（I8cf5a）
• 修复了诸如 .snapshot()、.peek() 等演示方 API 在 ListUpdateCallback 更新中返回先前（过时）列表的错误。
• 修复了在与 RemoteMediator 一起使用时，分隔符运算符不会添加标题或页脚的错误。
• 修复了 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）

错误修复

• RemoteMediator REFRESH 的 endOfPaginationReached 现在正确地传播到 LoadState 更新，并阻止远程 APPEND 和 PREPEND 触发。（I94a3f，b/155290248）
• 由于初始页面为空或过滤过于严格而呈现空列表将不再阻止 Paging 启动 PREPEND 或 APPEND 加载。（I3e702，b/168169730）
• 修复了当失效快速发生时，getRefreshKey 不会在 PagingSource 的后续生成中被调用的问题。（I45460，b/170027530）

外部贡献

• 已添加一个新的抽象类 InvalidatingPagingSourceFactory，它具有一个 .invalidate() API，该 API 将失效转发到它发出的所有 PagingSource。感谢 @claraf3！（Ie71fc，b/160716447）

已知问题

• 当使用 RemoteMediator 时，来自 .insertSeparators() 转换的标题和页脚可能不会立即出现 b/172254056
• 使用 RemoteMediator 可能会导致远程 LoadState 卡住，如果失效和 PagingSource.load(LoadParams.Refresh(...)) 在 RemoteMediator.load() 返回之前完成 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）

错误修复

• 修复了在使用分隔符和 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 中可用）来组合 DataSource.InvalidatedCallback 的 Kotlin/Java 变体。这也修复了在通过 .map 或 .mapByPage 转换后，Kotlin 变体的失效回调未被调用的错误。（I1f244，b/165313046）

错误修复

• Paging 与 ViewPager 的交互已得到显着改善。具体来说，Paging 将不再因页面失效而取消 RemoteMediator#load 调用。它还将在 REFRESH 请求成功完成之前，不再发出追加/预取加载请求（如果需要 REFRESH）。（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 变更

• 异步 PagingData 基于 Guava 的运算符现在接受 Executor 作为参数，以控制执行上下文。（Id4372）

错误修复

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

外部贡献

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

版本 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）

错误修复

• insertSeparators 不再过滤掉空页面，允许演示者即使在插入许多空页面时也能尊重预取距离。（I9cff6，b/162538908）

版本 3.0.0-alpha05

2020 年 8 月 19 日

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

错误修复

• Paging 现在即使在呈现的数据被大量过滤时也能正确预取页面。
• 将 LoadResult.Error 返回给重试加载不再会导致项目访问错误地重新触发重试

外部贡献

• 感谢 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)
• 弃用数据刷新 Flow / Listener API，因为它们旨在公开 REFRESH 上呈现的项目状态，但随着 loadState Flow / Listener 回调时序和 itemCount 属性的改进，它变得多余了 (Ia19f3)
• 为 PagingSource 和 RemoteMediator 添加了 RxJava3 兼容性包装器 (I49ef3, b/161480176)

错误修复

• PositionalDataSource 通过 toPagingSourceFactory 帮助程序转换为 PagingSource，包括现在由 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)
• 从 Java 中隐藏了 DataSource kotlin map 函数变体，以解决原始变体和 kotlin 变体之间的歧义。 (If7b23, b/161150011)
• 旨在为 Kotlin 用户提供便利的多余 API 已被标记为 @JvmSynthetic (I56ae5)
• 为 LoadResult.Page 的构造函数添加了重载，它将 itemsBefore 和 itemsAfter 默认为 COUNT_UNDEFINED (I47849)
• 使现有的 PagingData 运算符能够接受挂起方法，并为 Java 用户引入了新的 mapSync、flatMapSync 和 filterSync 非挂起运算符。现有的转换方法已移至扩展函数，因此 Kotlin 用户现在需要导入它们。 (I34239, b/159983232)

错误修复

• Room（以及 PositionalDataSource）PagingSource 现在将在第一页中显示前导分隔符，因此用户无需滚动即可显示它。 (I6f747, b/160257628)
• 占位符上的项目访问现在会正确地触发 PagingSource 加载，直到返回一个在由 PagingData.filter() 转换后满足请求索引的页面。 (I95625, b/158763195)
• 修复了在 PagingSource 返回错误后滚动有时会阻止 PagingDataAdapter.retry() 重试的错误。 (I1084f, b/160194384)
• 修复了在丢弃页面后项目访问可能不会加载页面，即使项目访问在预取距离内的问题。 (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)
• 适配器 API，dataRefreshFlow 和 dataRefreshListener 现在传递一个布尔值以指示 PagingData 是否为空 (I6e37e, b/159054196)
• 为 RemoteMediator 添加了 RxJava 和 Guava API - RxRemoteMediator 和 ListenableFutureRemoteMediator
• 为 PagingState 添加了帮助程序，用于常见的项目访问，例如 isEmpty() 和 firstItemOrNull() (I3b5b6, b/158892717)

错误修复

• 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 库已更新至 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.

错误修复

• 修复了在罕见情况下转换无效期间转换位置时发生的 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() 变体，它接受一个额外的回调，如果/当 pagedlist 在 diffing 后显示时触发。这允许您将 PagedList 交换与其他 UI 更新同步。 b/73781068
• PagedList.getLoadedCount() 添加了一个新方法，用来查询内存中已加载的项目数量。需要注意的是，如果禁用占位符，该返回值将始终等于 .size()。

错误修复

• 修复了在列表重复使用时进行差异比较时的竞态条件 b/111591017
• PagedList.loadAround() 现在在索引无效时抛出 IndexOutOfBoundsException。之前可能会以其他不明确的异常崩溃。
• 修复了极小的初始加载大小与数据不变会导致无法继续加载的情况 b/113122599

版本 2.0.0

版本 2.0.0

2018 年 10 月 1 日

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

错误修复

• 修复了使用 PositionalDataSource 和占位符时，在快速滚动过程中可能发生的崩溃 b/114635383.

版本 2.0.0-beta01

2018 年 7 月 2 日

错误修复

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

预 AndroidX 依赖项

对于以下的预 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 日

分页 1.0.1 发布，在 runtime 中修复了一个错误。我们强烈建议使用 1.0.1 以获得稳定性。Paging RxJava2 1.0.1 也已发布，与 1.0.0-rc1 相同。

错误修复

• 修复了 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 1.0.0 版本计划的新功能。请升级项目以使用 1.0.0-rc1，并帮助我们进行测试，以便我们能够发布一个稳定的 1.0.0 版本。

此版本没有更改，与 1.0.0-beta1 相同。

版本 1.0.0-beta1

2018 年 4 月 5 日

分页将在进入发布候选版本之前进行短暂的 Beta 测试。我们不打算为 Paging 1.0 进行进一步的 API 更改，任何 API 更改的标准都非常高。

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

这个新库提供了 LivePagedListBuilder 的 RxJava2 替代方案，能够构建 Observable 和 Flowable，并使用 Scheduler 而不是 Executor。

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 更改以明确执行程序在构建器中的作用

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

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

• 修复了 PagedList.mCallbacks 成员，使其成为私有成员。

错误修复

• LivePagedListBuilder 在指定的执行程序上触发初始 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 计划是进入 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 从接口更改为抽象类以启用映射功能。

错误修复

• 将构建器更改为最终类。 b/70848565
• Room DataSource 实现现在已修复，可以处理多表查询 - 此修复包含在 Room 1.1.0-beta1 中，见上文。
• 修复了一个错误，即如果启用占位符且总大小是页面大小的精确倍数，则 BoundaryCallback.onItemAtEndLoaded 不会为 PositionalDataSource 调用。

版本 1.0.0-alpha5

2018 年 1 月 22 日

错误修复

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