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

Paging

使用 Paging 库,您可以轻松在应用的 RecyclerView 中妥善地逐步加载数据。
最新更新时间 当前稳定版 下一候选版本 Beta 版 Alpha 版
2020 年 7 月 22 日 2.1.2 - - 3.0.0-alpha03

声明依赖项

如需添加 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-alpha02"

  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。如果您发现了新问题,或对此库的改进有自己的见解,请告诉我们。创建新问题前,请先查看此库中的现有问题。您可以点击星标按钮,为现有问题投票。

创建新问题

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

版本 3.0.0

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