Paging

使用 Paging 库，您可以更轻松地在应用的 RecyclerView 中逐步妥善地加载数据。

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

工件 稳定版 候选版本 Beta 版 Alpha 版
paging-* 3.1.1 - - 3.2.0-alpha01
paging-compose - - - 1.0.0-alpha15
此库的上次更新时间：2022 年 6 月 1 日

声明依赖项

如需添加 Paging 的依赖项，您必须将 Google Maven 代码库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

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

Groovy

dependencies {
  def paging_version = "3.1.1"

  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:1.0.0-alpha15"
}

Kotlin

dependencies {
  val paging_version = "3.1.1"

  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:1.0.0-alpha15")
}

如需了解如何使用 Kotlin 扩展，请参阅 ktx 文档。

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

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库的改进有自己的见解，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 3.2

版本 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() 不再对 Presenter 端的 CombinedLoadStates 有影响。添加了允许将 sourceLoadStates 和 remoteLoadStates 传入这些构造函数的新重载，以维持将 LoadStates 设置为完全终端（即 NotLoading(endOfPaginationReached = false)）的行为，并根据需要添加远程状态。如果未传递 LoadStates，则前一个 CombinedLoadStates 在收到静态 PagingData 时会在 Presenter 端保持不变。（Ic3ce5、b/205344028）

bug 修复

  • 现在，如果 PagingSource.getRefreshKey() 会返回 null，但设置了非 null initialKey，则 PagingSource.getRefreshKey() 的优先级会正确地高于 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 中包含这些提交内容。

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 状态始终设为 null
  • 现在，您可以在无效/新生成的 PagingData 上执行以往版本中的取消操作。您应该不再需要在 Flow<PagingData> 上使用 .collectLatest，但我们仍然建议您使用。
  • 从 PagingSource.load 中添加了 PagingSource.LoadResult.Invalid 作为新的返回类型，这会导致 Paging 舍弃向此 PagingSource 发出任何待处理或今后的加载请求，并使该请求失效。此返回类型旨在处理可能会从数据库或网络返回的可能无效或过时的数据。
  • 添加了 .onPagesPresented 和 .addOnPagesUpdatedListener presenter API。在界面中呈现页面后会立即触发这些 API。在以下情况下，网页可能会进行更新：
    • 完成了对新一代 PagingData 的初始加载（不管新一代 PagingData 是否包含对所呈现项的任何更改）。也就是说，如果新一代 PagingData 完成了初始加载，但因列表完全相同而未进行任何更新，其仍会触发此回调。
    • 插入了某个页面（即使插入的页面不包含任何新项）。
    • 丢弃了某个页面（即使丢弃的页面为空）。

版本 3.1.0-rc01

2021 年 11 月 3 日

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

bug 修复

  • 修复了以下情况下 .cachedIn() 中出现的竞态条件和内存泄漏的问题：在没有观察者时或观察者切换到新的 PagingData 期间，Paging 下游发送了多个加载事件。(Ib682e)

版本 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，endOfPaginationReached 现在调用 LoadType.REFRESH 时会始终返回 false。以前，endOfPaginationReached 调用 RemoteMediator（而非 PagingSource）REFRESH 时，可能会返回 true。此行为现在已整合为始终返回 false，因为 REFRESH 无法作为终端命令使用，而且现作为 API 协定的一部分记录在 LoadStates 中。在确定是否终止分页时，您应始终以 APPEND 或 PREPEND 指令为依据。(I047b6)

  • 现在，Paging 中的 LoadStates 会等待 PagingSource 和 RemoteMediator 发出有效值后，再在各代之间发出下游消息。这样可以防止新生成的 PagingData 在 CombinedLoadStates.source.refresh（如果它已处于 Loading 状态）中发送 NotLoading；对于刷新状态，现在新生成的 PagingData 会在启动时始终正确地处于“Loading”状态，而不是在某些情况下错误地首先重置为“NotLoading”。

    现在，您可以在无效/新生成的 PagingData 上执行以往版本中的取消操作。您应该不再需要在 Flow<PagingData> 上使用 .collectLatest，但我们仍强烈建议您使用。（I0b2b5、b/177351336、b/195028524）

  • presenter API 上的 .loadStateFlow 和 .addLoadStateListener 不再多余地发送初始 CombinedLoadStates，其 mediator 状态始终设为 null，source 状态设为NotLoading(endOfPaginationReached = false)。这意味着：

    1. 如果您使用 RemoteMediator，则系统始终会预设为 mediator 状态。
    2. 如果不再接收 PagingData 发送的真实 CombinedLoadStates，那么在 .loadStateFlow 上注册新的 loadState 监听器或新收集器时，系统不会再立即发出当前值。如果收集器或监听器在提交 PagingData 之前启动，就可能发生这种情况。(I1a748)

版本 3.1.0-alpha03

2021 年 7 月 21 日

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

API 变更

  • 将第三个 LoadResult 返回类型 LoadResult.Invalid 添加到 PagingSource 中。当 PagingSource.load 返回 LoadResult.Invalid 时，Paging 将舍弃加载的数据并使 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 用户需要添加对无效类型的检查。（Id6bd3、b/191806126、b/192013267）

bug 修复

  • 现在，如果通过 PagingSource.registerInvalidatedCallback 或 DataSource.addInvalidatedCallback 添加的失效回调是在已经无效的 PagingSource/DataSource 上注册的，那么它们会自动触发。这解决了在提供初始加载期间已经无效的源时导致 Paging 丢弃无效信号并卡住的竞态条件问题。此外，现在会在触发后正确移除失效回调，因为系统保证它们最多被调用一次。(I27e69)
  • 从最近实例化的 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。

    由于这些更新是与界面同步的，因此您可以调用 .snapshot、.getItemCount 等适配器方法，以在更新得以应用后检查状态。请注意，.snapshot() 会被显式调用，因为每次进行更新时运行该方法都可能占用大量资源。

    在以下情况下，网页可能会进行更新：

    • 完成了对新一代 PagingData 的初始加载（不管新一代 PagingData 是否包含对所呈现项的任何更改）。也就是说，如果新一代 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 发送空操作差异事件的问题，这个问题可能会导致某些监听器提前触发。（Ic507f、b/182510751）

外部贡献

  • 将已弃用的 PagedList compat API 添加到了 rxjava3 工件中（Id1ce2、b/182497591）

Paging Compose 版本 1.0.0

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

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) 现在会接受选项键参数，您可以使用此参数来指定表示该项的稳定键。您可以在此处详细了解有关键的信息。(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 和项 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，让它们仅能在 mediator 和 source 加载状态均为 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 库和 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.xx 中的大多数现有 API 已废弃，取而代之的是新的 Paging 3 API，这些 API 带来了以下改进：

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

版本 3.0.0-rc01

2021 年 4 月 21 日

发布了 androidx.paging:paging-*:3.0.0-rc01。版本 3.0.0-rc01 中包含这些提交内容。

bug 修复

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

版本 3.0.0-beta03

2021 年 3 月 24 日

发布了 androidx.paging:paging-*:3.0.0-beta03。版本 3.0.0-beta03 中包含这些提交内容。

bug 修复

  • 我们精心改进了重新加载列表时处理占位符的方式，以防止 RecyclerView 中出现意外跳转。如需了解详情，请参阅 NullP addedDiffing.md。（If1490、b/170027529、b/177338149）
  • 调用 .build() 时，各种 PagedList 构建器（旧兼容性路径）不会再错误地在主线程上同步调用 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“选择启用”要求。以前，Rx3 扩展是在 @get 方法中进行标记的，但该方法会被 Kotlin 编译器忽略，原因如下：https://youtrack.jetbrains.com/issue/KT-45227 (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 compat 封装容器，则现在需要使用 @OptIn(ExperimentalCoroutinesApi::class) 为使用情况添加注解 (Ib1f9d)

bug 修复

  • 修复了在通过兼容性路径使用 v2 DataSource API 时有时会抛出 IndexOutOfBoundsException: Inconsistency detected 的问题
  • 当通过兼容性路径使用 DataSource 时，DataSource 初始化期间的 isInvalid 调用现在会正确地在 fetchDispatcher 上（而不是在主线程上）启动。这修复了在使用 Room 的 PagingSource 实现时，由于在主线程上访问 Db 而产生的 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 - 仅等待 PagingSource 标记 endOfPaginationReached，即使使用了 RemoteMediator。这使得页眉和页脚可与初始加载内容同步显示，从而使用户无需滚动即可查看终端分隔符。（Ibe993、b/174700218）

bug 修复

  • 修复了在以下情况下发生的罕见内存泄漏：PagingSource 在 PageFetcher 可以开始从 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 用户添加了接受 ViewModel 而非 Lifecycle 或 CoroutineScope 的 .cachedIn() 重载。（I97d81、b/175332619）
  • 通过在转换运算符参数中接受执行器，允许 Java 调用方以异步方式使用 PagingData 转换操作。所有 -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 中包含这些提交内容。

新功能

  • 为以下基本用例添加了对“已保存状态”的支持（完全支持，尤其在分层来源用例正在执行过程中时）：
    • 流数据已缓存且应用未终止（例如：流数据已缓存在视图模型中，Activity 正在重新创建）
    • Paging 来源已统计，占位符已启用，且布局未交错。

API 变更

  • PagingSource.getRefreshKey() 现已是稳定的 API（I22f6f、b/173530980）
  • PagingSource.invalidate 不再是开放函数。如果您需要在无效情况发生时收到通知，请考虑调用 registerInvalidatedCallback 方法，而不是替换 invalidate。（I628d9、b/173029013、b/137971356）
  • 除了常规构造函数外，Pager 现在有了一个单独的实验性构造函数；而不是通过选择启用注解，将实验性 API 泄漏到非实验性公共 API 中。（I9dc61、b/174531520）
  • 更新了便捷属性 CombinedLoadStates.refresh、CombinedLoadStates.prepend、CombinedLoadStates.append，让它们仅能在 mediator 和 source 加载状态均为 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，那么 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，因为这些 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，该 API 会将无效信号转发给它发出的所有 PagingSource。感谢 @claraf3！（Ie71fc、b/160716447）

已知问题

  • 通过 .insertSeparators() 转换得出的页眉和页脚可能不会在使用 RemoteMediator 时立即显示 b/172254056
  • 如果在 RemoteMediator.load() 返回前便发生了无效情况且 PagingSource.load(LoadParams.Refresh(...)) 已运行完毕，那么使用 RemoteMediator 可能会导致远程 LoadState 卡住 b/173717820

版本 3.0.0-alpha09

2020 年 11 月 11 日

发布了 androidx.paging:paging-*:3.0.0-alpha09。版本 3.0.0-alpha09 中包含这些提交内容。

API 变更

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

bug 修复

  • 在对 RemoteMediator 使用分隔符时，在会返回 endOfPagination 的远程加载仍在运行时触发了 invalidate 的情况下会抛出 IllegalArgumentException，现在修复了这个问题 (I3a260)

版本 3.0.0-alpha08

2020 年 10 月 28 日

发布了 androidx.paging:paging-*:3.0.0-alpha08。版本 3.0.0-alpha08 中包含这些提交内容。

API 变更

  • 通过功能接口（在 Kotlin 1.4 中提供）启用了 SAM 转化，从而合并了 DataSource.InvalidatedCallback 的 Kotlin/Java 变体。这也修复了无效回调的 Kotlin 变体在被 .map 或 .mapByPage 转换后没有被调用的问题。（I1f244、b/165313046）

bug 修复

  • Paging 与 ViewPager 的交互已得到显著改善。具体而言，Paging 不会再因页面失效而取消 RemoteMediator#load 调用。如果需要进行 REFRESH，Paging 也不会再发出附加/前置加载请求，直到 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 变更

  • 基于 Guava 的异步 PagingData 运算符现在接受 Executor 作为参数，以控制执行环境。(Id4372)

bug 修复

  • 修复了因竞态条件导致 RemoteMediator 中抛出 IndexOutOfBounds 异常的问题。（I00b7f、b/165821814）
  • 修复了 DataSource 向 PagingSource 转换过程中发生的竞态条件，该问题可能会导致生成的 PagingSource 忽略来自 DataSource 的无效信号。
  • 修复了页面 fetchin 逻辑中的一个问题，该问题有时会导致在系统调用 PagingDataAdapter.refresh() 之前，该逻辑无法提取新生成的 PagingSource
  • 修复了可能导致以下情况的问题：当结合使用已转换成 PagingSource（例如由 Room 生成的 PagingSource）的 DataSource 与 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）

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 不会再导致项访问错误地重新触发重试

外部贡献

  • 感谢 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 流/侦听器 API，因为它们用于在 REFRESH 上公开所提供的项状态，但由于我们改进了 loadState 流/侦听器回调时机和 itemCount 属性，现在已不需要 dataRefresh 流/侦听器 API (Ia19f3)
  • 为 PagingSource 和 RemoteMediator 添加了 RxJava3 兼容性封装容器（I49ef3、b/161480176）

bug 修复

  • 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)
  • DataSource Kotlin 映射函数变体已对 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）PagingSource 现在会在首个页面中显示前导分隔符，从而无需用户滚动页面就能显示。（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)
  • 适配器 API dataRefreshFlow 和 dataRefreshListener 现在会传递一个布尔值，以指示 PagingData 是否为空（I6e37e、b/159054196）
  • 为 RemoteMediator（RxRemoteMediator 和 ListenableFutureRemoteMediator）添加了 RxJava 和 Guava API
  • 向 PagingState 添加了辅助程序（例如 isEmpty() 和 firstItemOrNull()），以获取通用项访问权限（I3b5b6、b/158892717）

bug 修复

  • 分页器现在会检查在工厂中重复使用 PagingSource 的情况，以防意外重复使用无效的 PagingSource（这会导致出现不明确的错误）（I99809、b/158486430）
  • RemoteMediator REFRESH 运行失败不会再导致 PagingSource 无法加载（I38b1b、b/158892717）
  • 在 submitData 的挂起版本之后调用 submitData 的非挂起版本时，后者不再会因多个 PagingData 上的并发收集而出现崩溃。（I26358、b/158048877）
  • 修复了在配置更改后可能发生的“无法从分页器收集两次”异常（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 的新功能

已知问题

  • 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 中发布的，但这次在版本 2.1.0 的基础上正确进行了挑选。如果您目前使用的是 2.1.1，强烈建议您升级到此版本。

版本 2.1.1

版本 2.1.1

2019 年 12 月 18 日

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

bug 修复

  • 停用占位符后，通过 PositionalDataSource 进行的连续初始加载现在会仅仅围绕上次访问执行

版本 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 时触发。这样，您可以将 PagedList 交换与其他界面更新同步。b/73781068
  • 添加了 PagedList.getLoadedCount()，以告知您内存中有多少项。请注意，如果停用了占位符，则返回值会一律等于 .size()。

bug 修复

  • 修复了在重复使用列表的情况下比较差异时的竞态条件问题 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 修复

  • 修复了在某些前置情况下（占位符已停用，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 日

发布了 Paging 1.0.1，该版本修复了 runtime 中的一个问题。为了保持稳定性，我们强烈建议使用 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 将在测试阶段进行短时间的测试。 我们不计划对 Paging 1.0 做出进一步的 API 更改，并且任何 API 变更的标准都非常高。

Alpha RxJava2 对 Paging 的支持作为一个单独的可选模块 (android.arch.paging:rxjava2:1.0.0-alpha1) 发布，并且将暂时单独版本化，直到它稳定为止。

此新库提供了 RxJava2 来替代 LivePagedListBuilder，能够构造 Observable 和 Flowable，接受 Scheduler 而不是 Executor：

Kotlin

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

Java

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

新功能

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

API 变更

  • 进行了 API 变更，以阐明执行器在构建器中的作用：

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

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

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

bug 修复

  • LivePagedListBuilder 将在指定的执行器上（而不是在架构组件 IO 线程池中）触发初始 PagedList 加载。

  • 修复了内部 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 进入测试阶段之前，计划将 Paging alpha7 作为最终版本。

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 从接口更改为抽象类以启用映射功能。

bug 修复

  • 构建器已更改为最终版本。 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