Paging

Paging 程式庫可讓您在應用程式的RecyclerView中更輕鬆簡單地逐漸載入資料。

這個資料表會列出 androidx.paging 群組中的所有構件。

構件 穩定版 候選版 Beta 版 Alpha 版
paging-* 3.3.4 - - -
paging-compose 3.3.4 - - -
本程式庫上次更新日期：2024 年 11 月 13 日

宣告依附元件

如果要在 Paging 新增依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

Groovy

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

Kotlin

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。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

3.3 版

3.3.4 版

2024 年 11 月 13 日

發布 androidx.paging:paging-*:3.3.4。3.3.4 版包含這些修訂版本。

修正錯誤

  • 從 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 Multiplatform 目標：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。
  • 在 hasError 和 isIdle 中新增 LoadStates 和 CombinedLoadStates 輔助方法，分別檢查 LoadStates 是否處於錯誤或 NotLoading 狀態。我們也已在 Flow<CombinedLoadStates> 上新增了新的 awaitNotLoading() Kotlin 擴充功能方法，可等待載入作業進入 NotLoading 或錯誤狀態。
  • PagingData.empty() 現在會依預設調度 NotLoading 狀態，除非自訂 LoadStates 已傳遞至其建構函式。這與現有行為不同，因為在提交至 PagingDataAdapter 時，系統不會調度 LoadStates，或是在收集為 LazyPagingItems 時調度 Loading 狀態。當資料以 LazyPagingItems 形式收集時，現在也會在初始組合時立即顯示空白清單。

Kotlin Multiplatform 相容性

Paging 現在會提供與 Kotlin Multiplatform 相容的構件，這要歸功於 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 版

March 20, 2024

發布 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，在 LoadStateFlow 上等待，直到載入作業進入 NotLoading 或錯誤狀態為止。(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 Multiplatform 相容性

Paging 現在會提供與 Kotlin Multiplatform 相容的構件，這要歸功於 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 變更

外部貢獻

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 版包含此連結所列的修訂項目。

修正錯誤

  • 修正問題：在傳遞使用 PagingData.from(List) 建構的資料流時，Paging Testing 構件會因 asSnapshot() 沒有任何載入完成時間資訊 (與 PagingData.from(List, LoadStates) 超載不同)，導致 asSnapshot() API 停止運作。這個解決方法只適用於可完成的資料流 (例如 flowOf(PagingData.from(...)))。如果是無法完成的資料流 (例如 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 現有的標準 items API，以及 HorizontalPager 等 API 中的等價項目。
    • items(lazyPagingItems) 和 itemsIndexed(lazyPagingItems) 僅支援 LazyListScope，已淘汰。
  • 新的 paging-testing 構件提供 API，專門針對應用程式各層的單元測試設計，並與 Paging 單獨整合。例如：
    • 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，您可以藉由可重複而一致的方式利用 API (例如 scrollTo 或 appendScrollWhile) 模擬應用程式介面，以便驗證分頁資料集中任何位置的資料快照是否正確。
  • 新增預設記錄，以便在 VERBOSE 和 DEBUG 兩個層級中顯示 Paging 偵錯資訊。您可以透過 adb shell setprop log.tag.Paging [DEBUG|VERBOSE] 指令啟用記錄功能。這適用於使用 View 的 Paging，以及使用 Compose 的 Paging。
  • 新增 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 版包含以下修訂項目。

外部貢獻

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 變更

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)
  • 新增 List<Value>.asPagingSourceFactory() 的 paging-testing API，以便取得只從不可變動的資料清單載入的 PagingSourceFactory。Flow<List<Value>> 的現有擴充功能仍可用於測試多個靜態資料世代。(Id34d1、b/280655188)。

API 變更

  • Paging 測試中的所有公開 API 現在都會加上 @VisibleForTesting 註解，確保這些 API 只用於測試。(I7db6e)
  • asSnapshot API 不再需要傳入 CoroutineScope。目前預設會使用從父項範圍繼承的背景資訊。(Id0a78、b/282240990)。
  • 重新排序 TestPager 建構函式參數，以便與實際 Pager 建構函式參數的順序相符 (I6185a)
  • 將分頁測試使用 lambda 類型 () -> PagingSource<Key, Value> 的用法遷移至 PagingSourceFactory<Key, Value> 類型。(I4a950、b/280655188)。

行為變更

  • 不再需要主調度器才能執行 asSnapshot Paging 測試。設定後，測試行為就不會再有任何變更。(Ie56ea)。

3.2.0-alpha05 版

2023 年 5 月 3 日

發布 androidx.paging:paging-*:3.2.0-alpha05。查看 3.2.0-alpha05 版的修訂項。

API 變更

  • asSnapshot 的 Paging Testing API 現在會將 loadOperations 參數預設為空 lambda。這樣一來，您就能呼叫 asSnapshot，而無須傳入任何載入作業，即可從初始重新整理載入作業中擷取資料。(Ied354、b/277233770)

說明文件改善項目

  • 更新 asPagingSourceFactory() 的說明文件，說明這是 Flow 上的擴充功能方法，可傳回可重複使用的工廠，用於產生 PagingSource 例項。(I5ff4f、I705b5)。
  • 更新 LoadResult.Page 建構函式的說明文件，清楚說明需要覆寫 itemsBefore 和 itemsAfter 才能支援跳轉。(Ied354)

外部貢獻

3.2.0-alpha04 版本

2023 年 2 月 8 日

發布 androidx.paging:paging-*:3.2.0-alpha04。查看 3.2.0-alpha04 版的修訂項。

Paging 測試

  • paging-testing 構件含有 asPagingSourceFactory 方法，可從要提供給 Pager 的 Flow<List<Value>> 建立 pagingSourceFactory。從 Flow 發出的每個 List<Value>> 都代表一代分頁資料。這有助於進行 Paging 測試，藉由虛構 Pager 收集的資料來源，測試 PagingData 轉換。(I6f230、b/235528239)

  • paging-testing 構件已藉由新的 API 加以擴充，這些 API 適合驗證含有 Flow<PagingData<T>> 的資料是否正確。比如，它可用於斷言 ViewModel 層的 Flow<PagingData<T>> 輸出內容。

    這是透過 Flow<PagingData<Value>> 上的 asSnapshot Kotlin 擴充功能達成，後者會將 Flow<PagingData<Value>> 轉換為直接 List<Value>。透過 asSnapshot lambda，您可以藉由可重複而一致的方式利用 API (例如 scrollTo 或 appendScrollWhile) 模擬應用程式介面，以便驗證分頁資料集中任何位置的資料快照是否正確。

    // 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 是應於 runTest 中執行的 suspend 方法。詳情請參閱「在 Android 上測試 Kotlin 協同程式」。(I55fd2、I5bd26、I7ce34、I51f4d、I2249f、Id6223、Ic4bab、Ib29b9、Ic1238、I96def、b/235528239)

API 變更

  • AsyncPagingDataDiffer 和 PagingDataAdapter 中對 getItem 和 peek 的使用者介面呼叫已正確標示為只能在主執行緒上呼叫。(I699b6)
  • 從 TestPager 使用的一般類型中移除萬用字元。如此一來，即可更輕鬆地在以 Java 程式設計語言編寫的程式碼中使用這些方法的執行結果。(I56c42)

3.2.0-alpha03 版本

2022 年 10 月 24 日

發布 androidx.paging:paging-*:3.2.0-alpha03。查看 3.2.0-alpha03 版的修訂項。

Paging 測試

這個版本包含一個新構件：paging-testing。這個構件提供的 API 專門針對應用程式各層的單元測試設計，並與 Paging 單獨整合。

舉例來說，這第一個版本包含 TestPager 類別，可讓您在 Pager 和通常需要模擬端對端 Paging 整合的實際使用者介面之外，獨立驗證自訂 PagingSource 實作項目的行為。

TestPager 應視為「fake」，即鏡射 Pager 實際實作的測試替身，同時提供用於測試 PagingSource 的簡化 API 介面。這些 API 是 suspend API，應如「在 Android 上測試 Kotlin 協同程式」指南所述在 runTest 中執行。

您可以在 room-paging 測試中找到這些使用中 API 的範例，經過重構可使用 TestPager。

API 變更

  • 透過 LoadResult.Page.iterator() 啟用便捷的 LoadResult.Page.data 疊代。這樣就會在指定 List<LoadResult.Page> 時 (例如將 PagingState 的 pages 屬性傳遞給 PagingSource.getRefreshKey 方法，間接開放使用 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)

修正錯誤

  • 修正搭配執行階段 paging-runtime:3.1.1 以下版本使用 paging-common:3.2.0-alpha01 時發生的缺少 PagingDataDiffer 建構函式錯誤。(b/235256201)

3.2.0-alpha01 版本

2020 年 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，則前一個 CombinedLoadStates 收到靜態 PagingData 時，將保留在展示器端。(Ic3ce5、b/205344028)

修正錯誤

  • 現在，如果傳回的結果是空值，但已設定非空值 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 版的修訂項。

修正錯誤

  • 已移除不同版本之間由 .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 不會再多餘地傳送中介者狀態一律設為 null 的初始 CombinedLoadStates
  • 過去幾代的功能現已因失去效力/新代出現而取消。在 Flow<PagingData> 中應已不再需要使用 .collectLatest，但還是建議使用。
  • PagingSource.LoadResult.Invalid 已新增為 PagingSource.load 的新傳回類型，而這會導致 Paging 捨棄所有對此 PagingSource 的待處理或後續載入要求，並使這些要求無效。此傳回類型經特別設計，可處理可能從資料庫或網路傳回且可能無效或過時的資料。
  • 已新增 .onPagesPresented 和 .addOnPagesUpdatedListener 簡報者 API，這些 API 會以 UI 中呈現的頁面方式同步觸發。在以下情況中，可能會有頁面更新：
    • 新一代 PagingData 的初始載入作業完成，不論新一代項目是否包含顯示項目的任何變更。例如：新一代在沒有更新的情況下完成初始載入，因為清單完全相同時仍會觸發這個回呼。
    • 即使插入的網頁不含任何新項目，系統還是會插入網頁。
    • 即使網頁已清空，系統也不會捨棄網頁。

3.1.0-rc01 版本

2021 年 11 月 3 日

發布 androidx.paging:paging-*:3.1.0-rc01。查看 3.1.0-rc01 版的修訂項。

修正錯誤

  • 修正以下情況下，.cachedIn() 中出現競爭狀況和記憶體流失的問題：在沒有觀察器，或觀察器切換至新的 PagingData 期間，Paging 下游傳送了多個載入事件。(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)

修正錯誤

  • 在 LoadState 中，LoadType.REFRESH 的 endOfPaginationReached 值現在一律是 false。先前，RemoteMediator REFRESH 的 endOfPaginationReached 可能是 true，但 PagingSource 不是。此行為已固定為一律傳回 false，因為將 REFRESH 做為終端指令沒有意義；這在 LoadState 中已記錄為 API 協定的一部分。在確定是否終止分頁時，您應該一律以 APPEND 或 PREPEND 指令做為依據。(I047b6)

  • Paging 的 LoadState 現在會等待 PagingSource 和 RemoteMediator 發出有效值之後，再於各世代之間向下游發出信號。這將防止新世代 PagingData 在 MergedLoadStates.source.refresh 中傳送 NotLoading (如果先前已處於 Loading 狀態)；現在新世代 PagingData 將一律正確地先以 Loading 做為重新整理狀態，而不會在某些情況下錯誤地先重設為 NotLoading。

    過去幾代的功能現已因失去效力/新代出現而取消。您應已不需要在 Flow<PagingData> 上使用 .collectLatest，但我們仍強烈建議您使用。(I0b2b5、b/177351336、b/195028524)

  • 展示器 API 上的 .loadStateFlow 和 .addLoadStateListener 不會再多餘地傳送中介者狀態一律設為 null、來源狀態一律設為 NotLoading(endOfPaginationReached = false) 的初始 CombinedLoadStates。這表示：

    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 傳回 LoadLoad.Invalid 時，Paging 會捨棄已載入的資料，並將 PagingSource 設為無效。此傳回類型旨在處理可能從資料庫或網路傳回可能無效或過時的資料。

    舉例來說，如果基礎資料庫已寫入，但 PagingSource 未及時設為無效，則如果其實作取決於其載入的幕後資料集不變性，就可能會傳回不一致的結果 (例如：LIMIT OFFSET 樣式 dB 實作)。在這個情況下，建議在載入後檢查是否設為無效，並傳回 LoadResult.Invalid。這樣一來，Paging 就會捨棄所有待處理的或日後載入至這個 PagingSource 的載入要求，並將之設為無效。

    此傳回類型也由採用 LivePagedList 或 RxPagedList 的 Paging2 API 支援。使用 PagingSource 搭配 Paging2 的 PagedList API 時，系統會立即與 PagedList 中斷連結，停止進一步嘗試在此 PagedList 中載入資料，並在 PagingSource 上觸發失效。

    LoadResult 是密封類別，代表這項變更與來源不相容，因此在直接使用 PagingSource.load 結果的情況下，必須在編譯時間處理 LoadResult.Invalid。舉例來說，Kotlin 使用者如果使用 exhaustive-when 檢查傳回類型，就必須加入無效類型的檢查。(Id6bd3、b/191806126、b/192013267)。

修正錯誤

  • 現在如果已在 PagingSource/DataSource 上失效，系統就會自動觸發透過 PagingSource.registerInvalidatedCallback 或 DataSource.addInvalidatedCallback 新增的無效回呼。這可解決導致 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 事件監聽器和流程簡報 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)。

修正錯誤

  • 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 版的修訂版本。

支援所有延遲版面配置

先前，Paging Compose 會在 LazyListScope 上提供自訂的 items 和 itemsIndexed 擴充功能，這表示您無法將 Paging Compose 與其他延遲版面配置 (例如 LazyVerticalGrid、HorizontalPager) 或 Wear 和 TV 程式庫提供的其他自訂延遲元件搭配使用。解決這個缺點是本版本的主要更新項目。

為了支援更多延遲版版面配置，我們需要在不同層級建構 API。Paging Compose 現在會在 itemKey 和 itemContentType 的 LazyPagingItems 上提供略低層級的擴充方法，而非為每個延遲版版面配置提供自訂 items API。這些 API 著重於協助您將 key 和 contentType 參數導入 LazyColumn 和 LazyVerticalGrid 現有的標準 items API，以及 HorizontalPager 等 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 的使用者而言，所有延遲版面配置的一致性都是重要的因素。因此，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 版的修訂項。

新功能

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-common:3.1.1 使用 paging-compose:1.0.0-alpha15 時發生的缺少 PagingDataDiffer 建構函式錯誤。(b/235256201、b/239868768)

1.0.0-alpha15 版本

2020 年 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 變更

  • 過去用於將 LazyColumn/Row 與 Paging 連結的 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 版包含此連結所列的修訂項目。

修正錯誤

  • LazyPagingItems 的 itemCount 和項目 getter 現為可觀察，因此也可與 LazyVerticalGrid 搭配使用 (Ie2446、b/171872064、b/168285687)

Compose 相容性

  • androidx.paging:paging-compose:1.0.0-alpha09 只與 1.0.0-beta07 以上的 Compose 版本相容。

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 改為從 Loading 到 NotLoading 採用中介服務和來源載入狀態 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 版的修訂項。

修正錯誤

  • 從 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 版的修訂項。

修正錯誤

  • 修正 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)。
  • 呼叫 .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 選擇加入的規定。先前這些會於 @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 compat 包裝函式，現在必須使用 @OptIn(ExperimentalCoroutinesApi::class) 註解用途 (Ib1f9d)

修正錯誤

  • 修正透過相容性路徑使用 v2 DataSource API 時，有時會擲回 IndexOutOfBoundsException: Inconsistency detected 的問題
  • 透過相容性路徑使用 DataSource 時，在初始化期間進行的 isInvalid 呼叫會正確地在 captureDispatcher 上啟動，而不是在主執行緒上啟動。修正使用聊天室的 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 - 只有在使用 RemoteMediator 時，才等待 PagingSource 標示 endOfPaginationReached。這可讓系統在初始載入時同步顯示標頭和頁尾，因此使用者不必捲動就看得到終端機分隔符。(Ibe993、b/174700218)。

修正錯誤

  • 修正以下情況發生的罕見記憶體流失問題：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 而不是 Lifecyle 或 CoroutineScope 的 .cachedIn() 超載。(I97d81、b/175332619)
  • 接受 Executor 做為轉換運算子引數，允許 Java 呼叫端能夠以非同步的方式使用 PagingData 轉換作業。所有 -Sync 轉換運算子現在都已移除 -Sync 字尾，而 Kotlin Coroutine 使用者必須呼叫改為接受暫停方塊的擴充功能函式以進行釐清。所有 PagingData 轉換運算子均已移至靜態 PagingDataTransforms 類別底下的擴充功能。Java 使用者必須透過靜態輔助程式呼叫，例如：PagingDataTransforms.map(pagingData, transform) 無為 Kotlin 使用者，語法相同，但必須匯入函式。(If6885、b/172895919)

修正錯誤

  • 修正當分頁已結束，不會在 adapter.refresh() 期間呼叫 RemoteMediator.load() 的錯誤。

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 現在也有一個實驗性建構函式；而不是透過選擇啟用註解，在非實驗性的公用 API 中提供實驗性 API。(I9dc61、b/174531520)
  • 已更新便利屬性，CombinedLoadStates.refresh、CombinedLoadStates.prepend，CombinedLoadStates.append 改為從 Loading 到 NotLoading 採用中介服務和來源載入狀態 NotLoading 確保已套用遠端更新。(I65619)

  • LoadParams.pageSize 已移除 (已不適用)。 建議在 PagingSource 中使用 LoadParams.loadSize。

    LoadParams.loadSize 一律等於 PagingConfig.pageSize，初始呼叫呼叫等於 PagingConfig.initialLoadSize 除外。

    如果測試 Paging2 DataSource 時，您並未使用 Pager 和 PagedList，而且設定了 initialLoadSize，pageSize 就可能與 PagingConfig.pageSize 不一致。如果這項設定具有必要性，請嘗試改用 Pager/PagedList，它將在內部針對您的 DataSource 載入方法設定正確的 PageSize。(I98ac7、b/149157296)

修正錯誤

  • 修正問題：在 PagingConfig.maxSize 已設定的情況下使用分隔符時，會因為 IllegalStateException 而發生當機。(I0ed33、b/174787528)
  • 修正問題：如果已設定 RemoteMediator，PREPEND/APPEND 的載入狀態就不會在初始載入後立即更新至 NotLoading(endOfPaginationReached = true) (I8cf5a)
  • 修正問題：展示器端 API (例如 .snapshot()、.peek() 等) 會傳回 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/Webhook 更新，所以已經移除。對於這些遷移，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)
  • 修正問題：無效情況快速發生時，後續產生的 PagingSource 不會呼叫 getRefreshKey。(I45460、b/170027530)

外部貢獻

  • 加入新的摘要類別 InvalidatingPagingSourceFactory，並有 .invalidate()，可轉寄無效狀態至其發出的所有 PagingSource。感謝 @claraf3！(Ie71fc、b/160716447)

已知問題

  • 使用 RemoteMediator 時，.insertSeparators() 轉換中的標頭和頁尾可能不會立即顯示 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 變更

  • 完全淘汰有 replaceWith 子句的 dataRefreshFlow/Listener 方法。(I6e2dd)

修正錯誤

  • 修正問題：當會傳回 endOfPagination 的遠端載入作業仍在執行時，使用 RemoteMediator 搭配分隔符會擲回 IllegalArgumentException 並觸發無效 (I3a260)

3.0.0-alpha08 版本

2020 年 10 月 28 日

發布 androidx.paging:paging-*:3.0.0-alpha08。查看 3.0.0-alpha08 版的修訂項。

API 變更

  • DataSource.InvalidatedCallback 的 Kotlin/Java 變體是透過功能介面 (Kotlin 1.4 提供)，在 Kotlin 中啟用 SAM 轉換功能合併而成。這同時修正了在 .map 或 .mapByPage 轉換之後，系統未呼叫無效回呼的 Kotlin 變體的錯誤。(I1f244、b/165313046)。

修正錯誤

  • Paging 與 ViewPager 的互動大幅提升。具體而言，Paging 將不再因網頁無效而取消 RemoteMediator#load 呼叫。而且，如需 REFRESH，在 REFRESH 要求順利完成前都不會再做出附加/前附的載入要求。(I6390b、b/162252536)
  • 已為 androidx (I4bbea、b/138602561) 啟用 API Lint 查找缺少 GetGetterMatchingBuilder
  • 修正 .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 的無效信號。
  • 修正頁面擷取邏輯問題，該問題有時會導致邏輯無法在 PagingDataAdapter.refresh() 受到叫用前，取得新產生的 PagingSource
  • 修正在使用已轉換成 PagingSource 的 DataSource (例如 Room 產生的 PagingSource) 搭配 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 版的修訂項。

修正錯誤

  • 現在即使呈現的資料經過重度篩選，系統仍可預先擷取網頁
  • 將 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()，以便在不觸發頁面擷取程序的情況下擷取顯示的項目。(I566b6、b/159104197)
  • 新增可用於顯示靜態清單的 PagingData.from(List<T>) 建構函式；這個建構函式可與 PagingData 整體流程搭配使用，藉此在特定狀態下 (例如在初始 REFRESH 完成之前，或單純用於測試轉換) 顯示靜態清單。(Id134d)
  • 淘汰 dataRefresh Flow/Listener API，因為它們的作用是在 REFRESH 上呈現顯示項目的狀態，但由於我們改進了 loadState Flow/Listener 回呼時機和 itemCount 屬性，所以已經不需要這兩個 API (Ia19f3)
  • 已為 PagingSource 和 RemoteMediator 新增 RxJava3 相容性包裝函式 (I49ef3、b/161480176)

修正錯誤

  • PositionalDataSource 已透過 toPagingSourceFactory 輔助功能轉換為 PagingSource (包括 Room 產生的 PagingSource)，現在可以正確標示以支援跳轉。(I3e84c、b/162161201)
  • 修正錯誤：提交 API 的同步變化版本有時會導致競爭而引發 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 對應函式變化版本，以解決原始和 Kotlin 版本之間模糊不清的問題。(If7b23、b/161150011)
  • 為方便 Kotlin 使用者使用的備援 API 已標示為 @JvmSynthetic (I56ae5)
  • 針對 LoadResult.Page 的建構函式新增超載值，該建構函式會將 itemCOUNT 和 itemsAfter 預設為 COUNT_UNDEFINED (I47849)
  • 使現有的 PagingData 運算子接受暫停方法，並為 Java 使用者導入新的 mapSync、FlatMapSync 和 filterSync 非暫停運算子。現有的轉換方法已移至擴充功能函式，因此 Kotlin 使用者現在需要匯入這些函式。(I34239、b/159983232)

修正錯誤

  • Room (和 PositionalDataSource) PagingSources 現在會在第一頁顯示前置分隔符，因此使用者不必捲動頁面也看得到分隔符。(I6f747、b/160257628)
  • 對預留位置的項目存取權將正確觸發 PagingSource 載入程序；直到傳回在經 PagingData.filter() 轉換後依要求編入索引的頁面時，才會停止載入 (I95625, b/158763195)
  • 修正 PagingSource 捲動後有時會傳回錯誤的錯誤，避免 PagingData 轉接程式.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 新增 RxJava 和 Guava API - RxRemoteMediator 和 ListenableFutureRemoteMediator
  • 在 PagingState 中針對常見項目存取加入輔助程式，例如 isEmpty() 和 firstItemOrNull() (I3b5b6、b/158892717)

修正錯誤

  • Pager 現在會檢查工廠中重複使用 PagingSource 的狀況，避免意外重複使用無效的 PagingSource，導致不明錯誤 (I99809、b/158486430)
  • RemoteRemotetor 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 的新功能

已知問題

  • Paging 3 javadocs 尚未提供。在這段期間，請使用上方連結的指南或 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 版的修訂項。

修正錯誤

  • 停用預留位置時，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 而觸發的回呼。這樣一來，您就可以將 PagedList 更換活動與其他 UI 更新項目同步處理。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 中發布) 修正了 PagedListAdapter 和 AsyncPagedListDiffer 無法發出移動事件信號的異常終止問題 b/110711937

Pre-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 完全相同。

修正錯誤

  • 修正導致 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 日 Pagig 推出候選版

我們在 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) 發布，在穩定前將暫時分為獨立版本。

這個新程式庫可讓您以 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 以闡明執行工具在建構工具中的作用：

    • setBackgroundThreadExecutor() 已重新命名為 setFetchExecutor() (在 PagedList.Builder 和 LivePagedListBuilder 中)

    • setMainThreadExecutor() 已重新命名為 setNotifyExecutor() (在 PagedList.Builder 中)。

  • 將 PagedList.mCallbacks 成員的狀態修正為不公開。

修正錯誤

  • LivePagedListBuilder 將在指定的執行工具 (而非 Arch 元件 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 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 從介面變更為抽象類別，以啟用對應功能。

修正錯誤

  • 將建構工具變更為最終版。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/70411933、b/71467637