Google 致力于为黑人社区推动种族平等。查看具体举措

Paging

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

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

工件 当前稳定版 下一候选版本 Beta 版 Alpha 版
paging-* 2.1.2 - - 3.0.0-alpha09
paging-compose - - - 1.0.0-alpha02
此库的最后更新时间:2020 年 11 月 11 日

声明依赖项

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

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

    dependencies {
      def paging_version = "2.1.2"

      implementation "androidx.paging:paging-runtime:$paging_version" // For Kotlin use paging-runtime-ktx

      // alternatively - without Android dependencies for testing
      testImplementation "androidx.paging:paging-common:$paging_version" // For Kotlin use paging-common-ktx

      // optional - RxJava support
      implementation "androidx.paging:paging-rxjava2:$paging_version" // For Kotlin use paging-rxjava2-ktx
    }
    

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

或者,您也可以试用 Paging 3.0 的 Alpha 版。如需使用 Paging 3.0,请将以下依赖项添加到 build.gradle 文件中:

dependencies {
  def paging_version = "3.0.0-alpha09"

  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 - Guava ListenableFuture support
  implementation "androidx.paging:paging-guava:$paging_version"

  // Jetpack Compose Integration
  implementation "androidx.paging:paging-compose:1.0.0-alpha02"
}

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

反馈

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

创建新问题

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

Paging Compose 版本 1.0.0

版本 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 提供相同的功能( Iddfe8b/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.0

版本 3.0.0-alpha09

2020 年 11 月 11 日

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

API 变更

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

问题修复

  • 在对 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 转换后没有被调用的问题。(I1f244b/165313046

问题修复

  • Paging 与 ViewPager 的交互已得到显著改善。具体而言,Paging 不会再因页面失效而取消 RemoteMediator#load 调用。如果需要进行 REFRESH,Paging 也不会再发出附加/前置加载请求,直到 REFRESH 请求成功完成为止。I6390bb/162252536
  • 针对 androidx 启用了 MissingGetterMatchingBuilder 的 API lint 检查(I4bbeab/138602561
  • 修复了 .withLoadState* ConcatAdapter 帮助程序在从后台线程通知 RecyclerView 时会发生崩溃的问题(I18bb5b/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)

问题修复

  • 修复了因竞态条件导致 RemoteMediator 中抛出 IndexOutOfBounds 异常的问题。(I00b7fb/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。(Ib3890b/158801427

问题修复

  • insertSeparators 不再过滤出空白页,以便 Presenter 遵从预取距离,即使在插入多个空白页的情况下也是如此。(I9cff6b/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 变更

  • AsyncPagingDataDifferPagingDataAdapter 中添加了 peek() API,以允许在不触发页面加载的情况下访问所提供的数据。(I38898b/159104197
  • PagingDataAdapterAsyncPagingDataDiffer 中添加了 snapshot() API,以允许在不触发页面提取的情况下检索提供的项。(I566b6b/159104197
  • 添加了 PagingData.from(List<T>) 构造函数以允许显示静态列表,该列表可与总体 PagingData 流组合使用以在特定状态(例如,在初始 REFRESH 操作完成之前或仅用于测试转换时)显示静态列表。(Id134d)
  • 弃用了 dataRefresh 流/侦听器 API,因为它们用于在 REFRESH 上公开所提供的项状态,但由于我们改进了 loadState 流/侦听器回调时机和 itemCount 属性,现在已不需要 dataRefresh 流/侦听器 API (Ia19f3)
  • PagingSourceRemoteMediator 添加了 RxJava3 兼容性封装容器(I49ef3b/161480176

问题修复

  • PositionalDataSource 已通过 toPagingSourceFactory 帮助程序转换为 PagingSource,包括由 Room 生成的 PagingSource 现在可以正确进行自我标记以支持跳转。(I3e84cb/162161201
  • 修复了如下错误:使用 submitData 的同步变体有时会导致争用而引发 ClosedSendChannelException (I4d702b/160192222)

外部贡献

  • 感谢 Zac Sweers 代表 Slack 添加了 RxJava3 兼容性封装容器!(I49ef3b/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 变体之前的歧义。(If7b23b/161150011
  • Kotlin 用户专用的冗余 API 已被标记为 @JvmSynthetic (I56ae5)
  • 为 LoadResult.Page 的构造函数添加了重载,会将 itemsBefore 和 itemsAfter 默认设置为 COUNT_UNDEFINED (I47849)
  • 使现有的 PagingData 运算符接受挂起方法,并为 Java 用户引入了新的非挂起运算符:mapSync、flatMapSync 和 filterSync。现有转换方法已移至扩展函数,因此 Kotlin 用户现在需要导入这些方法。(I34239b/159983232

问题修复

  • Room(和 PositionalDataSource)PagingSource 现在会在首个页面中显示前导分隔符,从而无需用户滚动页面就能显示。(I6f747b/160257628
  • 现在,凭借对占位符的项访问权限,系统可以正确触发 PagingSource 加载;直至返回在经 PagingData.filter() 转换后按要求编入索引的页面时,加载方会停止(I95625b/158763195
  • 修正了以下错误:PagingSource 返回错误后页面有时会滚动,可能导致 PagingDataAdapter.retry() 无法执行重试操作。(I1084fb/160194384
  • 修正了以下问题:尽管项访问权限的作用范围为 prefetchDistance,但在丢弃某个页面后,即使有项访问权限系统也可能不会加载页面(Ie95aeb/160038730
  • 在发生丢弃事件后,设置“PagingConfig.maxSize”不会再启用占位符(I2be29b/159667766

版本 3.0.0-alpha02

2020 年 6 月 24 日

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

API 变更

  • PagingConfig 的构造函数(带有常用默认值)添加了重载(I39c50b/158576040
  • PagingDataAdapterAsyncPagingDataDiffer 的构造函数(带有常用默认值)添加了重载 (Ie91f5)
  • 适配器 API dataRefreshFlowdataRefreshListener 现在会传递一个布尔值,以指示 PagingData 是否为空(I6e37eb/159054196
  • 为 RemoteMediator(RxRemoteMediatorListenableFutureRemoteMediator)添加了 RxJava 和 Guava API
  • 向 PagingState 添加了辅助程序(例如 isEmpty()firstItemOrNull()),以获取通用项访问权限(I3b5b6b/158892717

问题修复

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

问题修复

  • 修复了失效期间转换位置时,在极少数情况下出现的 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 中包含以下提交内容

问题修复

  • 停用占位符后,通过 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()

问题修复

  • 修复了在重复使用列表的情况下比较差异时的竞争条件问题 b/111591017
  • 当索引无效时,PagedList.loadAround() 现在会抛出 IndexOutOfBoundsException。之前,它可能会发生崩溃,并抛出不明确的其他异常。
  • 修复了极小初始负载在数据未更改时导致不再继续加载的问题 b/113122599

版本 2.0.0

版本 2.0.0

2018 年 10 月 1 日

发布了 Paging 2.0.0,该版本修复了一个问题。

问题修复

  • 修复了在使用 PositionalDataSource 和占位符的情况下进行非常快速的滚动时可能会发生崩溃的问题。b/114635383

版本 2.0.0-beta01

2018 年 7 月 2 日

问题修复

  • 修复了在某些前置情况下(占位符已停用,PositionalDataSource)内容消失的问题 b/80149146
  • (在 1.0.1 中已发布)修复了导致 PagedListAdapterAsyncPagedListDiffer 无法发出移动事件信号的崩溃问题。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 完全相同。

问题修复

  • 修复了导致 PagedListAdapterAsyncPagedListDiffer 无法发出移动事件信号的崩溃问题。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,能够构造 ObservableFlowable,接受 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.BuilderLivePagedListBuilder 中)将 setBackgroundThreadExecutor() 重命名为 setFetchExecutor()

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

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

问题修复

  • 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 或通过模拟回调直接测试 DataSourceb/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 中,参见上文。
  • 修复了在启用占位符后且总大小为页面大小的整数倍时无法为 PositionalDataSource 调用 BoundaryCallback.onItemAtEndLoaded 的错误。

版本 1.0.0-alpha5

2018 年 1 月 22 日

问题修复

  • 修复了停用占位符后的页面加载问题 b/70573345
  • 添加了跟踪 IllegalArgumentException 错误的日志记录 b/70360195(以及推测性 Room 端修复)
  • 修复了 Javadoc 示例代码 b/70411933b/71467637