Bermigrasi ke Paging 3

Paging 3 sangat berbeda dengan versi Paging library yang sebelumnya. Versi ini memberikan fungsi yang disempurnakan, dukungan kelas satu untuk coroutine Kotlin dan Flow, serta integrasi yang lancar dengan Jetpack Compose.

Manfaat melakukan migrasi ke Paging 3

Paging 3 memiliki fitur berikut yang tidak ada di versi library sebelumnya:

  • Dukungan kelas satu untuk Flow dan coroutine Kotlin.
  • Status pemuatan bawaan dan sinyal error untuk desain UI yang responsif, termasuk fungsi coba lagi (retry) dan refresh.
  • Peningkatan di lapisan repositori, termasuk dukungan pembatalan dan antarmuka sumber data yang disederhanakan.
  • Peningkatan di lapisan presentasi, pemisah daftar, transformasi halaman kustom, header dan footer, serta item status pemuatan untuk daftar lambat.

Memigrasikan aplikasi ke Paging 3

Untuk sepenuhnya bermigrasi ke Paging 3, Anda harus memigrasikan komponen utama ini dari Paging 2:

  • Class DataSource
  • PagedList
  • Lapisan presentasi (ke LazyPagingItems)

Namun, ada beberapa komponen Paging 3 yang memiliki kompatibilitas mundur dengan versi Paging sebelumnya. Secara khusus, Pager API dapat menggunakan objek DataSource lama dengan metode asPagingSourceFactory. Dengan begitu, Anda memiliki opsi migrasi sebagai berikut:

  • Anda dapat memigrasikan DataSource ke PagingSource tanpa mengubah penerapan Paging lainnya.
  • Anda dapat memigrasikan seluruh penerapan Paging untuk memigrasikan aplikasi sepenuhnya ke Paging 3.

Bagian di halaman ini menjelaskan cara memigrasikan komponen Paging di setiap lapisan aplikasi Anda.

Class DataSource

Bagian ini menjelaskan semua perubahan yang diperlukan untuk memigrasikan penerapan Paging versi lama agar dapat menggunakan PagingSource.

Semua PageKeyedDataSource, PositionalDataSource, dan ItemKeyedDataSource dari Paging 2 digabungkan ke dalam API PagingSource dalam Paging 3. Metode pemuatan dari semua class API versi lama digabungkan menjadi satu metode load di PagingSource. Tindakan ini akan mengurangi duplikasi kode karena banyak logika yang sering kali identik di seluruh metode pemuatan di dalam penerapan class API versi lama.

Semua parameter metode pemuatan diganti dalam Paging 3 dengan class tertutup LoadParams yang menyertakan subclass untuk setiap jenis pemuatan. Jika Anda perlu me mbedakan jenis muatan di metode load, periksa subclass LoadParams yang diteruskan, apakah LoadParams.Refresh, LoadParams.Prepend, atau LoadParams.Append.

Untuk mempelajari penerapan PagingSource lebih lanjut, lihat Menentukan sumber data.

Me-refresh kunci

Implementasi PagingSource harus menentukan cara refresh dilanjutkan dari tengah data halaman yang dimuat. Lakukan hal ini dengan menerapkan getRefreshKey untuk memetakan kunci awal yang tepat dengan state.anchorPosition sebagai indeks yang terakhir diakses.

// Replaces ItemKeyedDataSource.
override fun getRefreshKey(state: PagingState<String, User>): String? {
  return state.anchorPosition?.let { anchorPosition ->
    state.getClosestItemToPosition(anchorPosition)?.id
  }
}

// Replacing PositionalDataSource.
override fun getRefreshKey(state: PagingState<Int, User>): Int? {
  return state.anchorPosition
}

Mentransformasi daftar

Dalam versi library Paging yang lebih rendah, transformasi data yang dibagi bergantung pada metode berikut:

  • DataSource.map
  • DataSource.mapByPage
  • DataSource.Factory.map
  • DataSource.Factory.mapByPage

Dalam Paging 3, semua transformasi diterapkan sebagai operator pada PagingData. Jika salah satu metode di daftar versi lama digunakan untuk mentransformasi daftar yang dibagi, Anda harus memindahkan logika transformasi dari DataSource ke PagingData saat mengkonstruksi Pager dengan PagingSource yang baru.

Untuk mempelajari cara menerapkan transformasi ke data halaman menggunakan Paging 3 lebih lanjut, lihat Mentransformasi aliran data.

PagedList

Bagian ini menjelaskan semua perubahan yang diperlukan untuk memigrasikan penerapan Paging sebelumnya agar dapat menggunakan Pager dan PagingData dalam Paging 3.

Class PagedListBuilder

PagingData menggantikan PagedList yang ada dari Paging 2. Untuk memigrasikannya ke PagingData, Anda harus memastikan hal berikut:

  • Konfigurasi Paging telah dipindahkan dari PagedList.Config ke PagingConfig.
  • Class builder lama telah digabung menjadi satu class Pager.
  • Pager menampilkan Flow<PagingData> yang dapat diamati dengan properti .flow-nya.
val flow = Pager(
  // Configure how data is loaded by passing additional properties to
  // PagingConfig, such as prefetchDistance.
  PagingConfig(pageSize = 20)
) {
  ExamplePagingSource(backend, query)
}.flow
  .cachedIn(viewModelScope)

Untuk mempelajari cara menyiapkan aliran reaktif objek PagingData menggunakan Paging 3, lihat Menyiapkan aliran PagingData.

BoundaryCallback untuk sumber berlapis

Dalam Paging 3, RemoteMediator menggantikan PagedList.BoundaryCallback sebagai a pengendali untuk melakukan paging dari jaringan dan database.

Untuk mempelajari penggunaan RemoteMediator untuk melakukan page dari jaringan dan database di Paging 3 lebih lanjut, lihat Codelab Paging Android.

LazyPagingItems

Bagian ini menjelaskan semua perubahan yang diperlukan untuk memigrasikan penerapan Paging versi lama agar dapat menggunakan LazyPagingItems dari Paging 3.

Paging 3 menyediakan collectAsLazyPagingItems untuk menangani aliran PagingData yang baru. Untuk memigrasikan lapisan presentasi, gunakan artefak paging-compose dan collectAsLazyPagingItems untuk mengumpulkan item PagingData dan menampilkannya dalam fungsi @Composable.

Untuk mempelajari LazyPagingItems lebih lanjut, lihat Memuat dan menampilkan data yang dibagi-bagi.

Perbedaan dan pembaruan daftar

Jika Anda sedang menggunakan logika perbedaan daftar kustom, migrasikan penerapan agar dapat menggunakan LazyPagingItems yang disediakan di Paging 3. Untuk memastikan perbedaan terjadi dengan benar, tentukan kunci item di daftar lambat:

@Composable
fun UserScreen(viewModel: UserViewModel) {
    // Collects the Flow into a LazyPagingItems object
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserScreen(viewModel: UserViewModel) {
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserList(lazyPagingItems: LazyPagingItems<User>) {
    LazyColumn {
        items(
            count = lazyPagingItems.itemCount,
            // Provide a stable key for each item, similar to DiffUtil in Views
            key = lazyPagingItems.itemKey { user -> user.id } 
        ) { index ->
            val user = lazyPagingItems[index]
            if (user != null) {
                UserRow(user = user)
            }
        }
    }
}

Untuk mengetahui informasi selengkapnya tentang kunci item, lihat Kunci item.

Status pemuatan

Di Paging 3, Anda tidak memerlukan adapter terpisah untuk menampilkan header atau footer untuk status pemuatan. Objek LazyPagingItems menampilkan properti loadState yang dapat Anda periksa langsung dalam LazyColumn.

LazyColumn {
    // ... items(lazyPagingItems) go here ...

    // Show loading spinner at bottom of list when appending data
    if (lazyPagingItems.loadState.append is LoadState.Loading) {
        item {
            CircularProgressIndicator(modifier = Modifier.fillMaxWidth())
        }
    }
}

Referensi lainnya

Untuk mempelajari library Paging lebih lanjut, lihat referensi tambahan berikut:

Dokumentasi

Melihat konten