Paging
這個資料表會列出 androidx.paging
群組中的所有構件。
構件 | 穩定版 | 候選版 | Beta 版 | Alpha 版 |
---|---|---|---|---|
paging-* | 3.3.2 版 | - | - | - |
paging-compose | 3.3.2 版 | - | - | - |
宣告依附元件
如果要在 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.2 版
2024 年 8 月 7 日
發布 androidx.paging:paging-*:3.3.2
。3.3.2 版包含這些修訂版本。
新功能
3.3.1 版
2024 年 7 月 24 日
發布 androidx.paging:paging-*:3.3.1
。3.3.1 版包含這些修訂版本。
修正錯誤
- 修正問題:當備份資料來源在捲動時重新整理時,
AsyncPagingDataDiffer
或以RecyclerView
搭配的PagingDataAdapter
為基礎建構的 API 無法觸發更多載入事件。(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
時分派載入狀態。如果收集為LazyPagingItems
,現在也會在初始組成時立即顯示空白清單。
Kotlin 多平台相容性
Paging 現在會提供與 Kotlin Multiplatform 相容的構件,這主要要歸功於 CashApp 的 multiplatform-paging 專案的上游作業。
paging-common
已將所有 Paging 3 API 移至common
,現在除了 Android 外,也與 jvm 和 iOS 相容。paging-testing
的程式碼已移至common
,且除了 Android 以外,現在也與 jvm 和 iOS 相容。paging-compose
已將其程式碼移至common
,並出貨與androidx.compose
的多平台支援相符的 Android 構件。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
狀態。此外,也新增了要在LoadStateFlow
上等待的新 API,直到載入作業設定為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 Multiplatform 相容的構件,這主要要歸功於 CashApp 的 multiplatform-paging 專案的上游作業。這可讓我們避免兩個存放區之間有所出入,並確保存放區保持相容。
paging-common
已將所有 Paging 3 API 移至common
,現在除了 Android 外,也與 jvm 和 iOS 相容。paging-testing
的程式碼已移至common
,且除了 Android 以外,現在也與 jvm 和 iOS 相容。paging-compose
已將其程式碼移至common
,並出貨與androidx.compose
的多平台支援相符的 Android 構件。paging-runtime
、paging-guava
、paging-rxjava2
和paging-rxjava3
仍僅限 Android 裝置。
API 變更
- 僅供內部使用的公開 Logger 介面已淘汰 (I16e95、b/288623117)
外部貢獻
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)
建構的 Flow 時,Paging 測試構件的asSnapshot()
API 會停止運作,因為asSnapshot()
在載入完成時不會有任何資訊 (與PagingData.from(List, LoadStates)
超載不同)。這個解決方法僅適用於可完成的流程 (例如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)
並在MutableStateFlow
中納入該PagingData
(例如MutableStateFlow(PagingData.from(listOf(1, 2, 3)))
)。將此資料流傳遞至@Preview
可組合項做為接收器,以供collectAsLazyPagingItems()
預覽。 - 支援所有延遲版面配置 (例如
LazyVerticalGrid
和HorizontalPager
),以及 Wear 和 TV 程式庫的自訂延遲元件。這項操作是透過新的較低層級的LazyPagingItems
擴充功能方法itemKey
和itemContentType
來達成,可協助您在LazyColumn
的現有標準items
API、LazyVerticalGrid
和HorizontalPager
等 API 中,實作key
和contentType
參數。 - 僅支援
LazyListScope
的items(lazyPagingItems)
和itemsIndexed(lazyPagingItems)
已淘汰。
- 支援預覽假資料清單,方法是建立
- 新的
paging-testing
構件提供 API 針對應用程式各層進行單元測試而設計的 API,並與 Paging 單獨整合。舉例來說,它包含TestPager
類別可讓您獨立驗證自訂PagingSource
實作的行為,不受 Pager 和實際 UI 影響。asPagingSourceFactory
API 可將Flow<List<Value>>
或靜態List<Value>
轉換為PagingSourceFactory
,以便在測試中傳遞至 PagerFlow<PagingData<Value>>
上的asSnapshot
Kotlin 擴充功能,可將Flow<PagingData<Value>>
轉換為直接List<Value>
。asSnapshot lambda
可讓您透過scrollTo
或appendScrollWhile
等 API 模擬應用程式的使用者介面,方便您驗證分頁資料集內任何時間點的資料快照是否正確。
- 新增了預設記錄,在兩個層級公開 Paging 偵錯資訊:
VERBOSE
和DEBUG
。您可以透過adb shell setprop log.tag.Paging [DEBUG|VERBOSE]
指令啟用記錄檔。這適用於含有檢視畫面的分頁或使用 Compose 分頁。 - 已新增
PagingDataAdapter
和AsyncPagingDataDiffer
的建構函式,其接受CoroutineContext
而非CoroutineDispatcher
。 - 已新增
PagingSourceFactory
功能介面,提供比上一個 () 更明確的 API 介面 ->PagingSource
lambda。這個工廠可以用來將 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 變更
- 已從 Paging Compose 中移除已淘汰的
items(LazyPagingItems)
和itemsIndexed(LazyPagingItems)
API。如需替換 API 的範例,請參閱 Paging Compose1.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) - 新增了
List<Value>.asPagingSourceFactory()
的paging-testing
API,取得只會從不可變動資料清單載入的PagingSourceFactory
。Flow<List<Value>>
上現有的擴充功能仍應用於針對多代靜態資料進行測試。(Id34d1、b/280655188)
API 變更
- 分頁測試中的所有公用 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)。
外部貢獻
- 感謝 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 測試
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
。先前,RemoteMediatorREFRESH
的 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
。這表示:- 如果您使用 RemoteMediator,則系統會一律填入中介者狀態。
- 在
.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)
並在MutableStateFlow
中納入該PagingData
(例如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 現在針對 itemKey
和 itemContentType
的 LazyPagingItems
提供略低的擴充功能方法。這些 API 著重於協助您將 key
和 contentType
參數實作至 LazyColumn
、LazyVerticalGrid
及 HorizontalPager
等 API 中既有的標準 items
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 時,所有 Lazy 版面配置的一致性都是相當重要的因素。因此,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-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 變更
- 在
LazyPagingItem
s 中新增.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)
修正錯誤
- 修正因 IllegalStateException 而造成的當機 搭配 PagingConfig.maxSize 設定使用分隔符(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 }
修正錯誤
- 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 變更
- 已將
peek()
API 新增至AsyncPagingDataDiffer
和 使用PagingDataAdapter
即可允許在不觸發觸發條件的情況下存取提供的資料 載入。(I38898、b/159104197) - 已將
snapshot()
API 新增至PagingDataAdapter
和AsyncPagingDataDiffer
,允許在不使用時擷取顯示項目 觸發網頁擷取作業。(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 的新功能
- 優質的 Kotlin 協同程式和流程支援。
- 支援使用協同程式暫停函式、RxJava Single 或 Guava immersiveableFuture 原始版本的非同步載入功能。
- 適用於回應式使用者介面設計的內建載入狀態和錯誤信號,包括重試和重新整理功能。
- 改善存放區層
- 簡化的資料來源介面
- 簡化的網路 + 資料庫分頁
- 取消支援
- 改善簡報圖層
已知問題
- 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