Bermigrasi ke Paging 3

Paging 3 sangat berbeda dengan versi Paging library yang sebelumnya. Versi ini memberikan fungsi yang disempurnakan dan menangani kesulitan umum dalam penggunaan Paging 2. Jika aplikasi Anda sudah menggunakan library Paging versi sebelumnya, baca halaman ini untuk mempelajari proses migrasi ke Paging 3 lebih lanjut.

Jika Paging 3 adalah library Paging versi pertama yang Anda gunakan di aplikasi, lihat Memuat dan menampilkan data yang di-page untuk informasi tentang penggunaan dasar.

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.
  • Dukungan untuk pemuatan asinkron menggunakan primitif Single dari RxJava atau ListenableFuture dari Guava.
  • 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, serta header dan footer status pemuatan.

Memigrasikan aplikasi ke Paging 3

Untuk sepenuhnya bermigrasi ke Paging 3, ketiga komponen utama dari Paging 2 harus dimigrasikan:

  • Class DataSource
  • PagedList
  • PagedListAdapter

Namun, ada beberapa komponen Paging 3 yang memiliki kompatibilitas mundur dengan versi Paging sebelumnya. Secara khusus, API PagingSource dari Paging 3 dapat menjadi sumber data untuk LivePagedListBuilder dan RxPagedListBuilder dari versi sebelumnya. Demikian pula, API Pager dapat menggunakan objek DataSource versi 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 PagedList dan PagedListAdapter sambil tetap menggunakan API DataSource versi lama.
  • 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 membedakan 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.

Kotlin

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

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

Java

// Replaces ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replaces PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState) {
  return state.anchorPosition;
}

Java

// Replacing ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replacing PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState) {
  return state.anchorPosition;
}

Mentransformasi daftar

Dalam versi library Paging sebelumnya, 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.
  • LivePagedListBuilder dan RxPagedListBuilder telah digabung menjadi satu class Pager.
  • Pager menampilkan Flow<PagingData> yang dapat diamati dengan properti .flow-nya. Varian RxJava dan LiveData juga tersedia sebagai properti ekstensi, yang dapat dipanggil dari Java melalui metode statis, serta disediakan masing-masing dari modul paging-rxjava* dan paging-runtime.

Kotlin

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)

Java

// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
Pager<Integer, User> pager = Pager<>(
  new PagingConfig(/* pageSize = */ 20),
  () -> ExamplePagingSource(backend, query));

Flowable<PagingData<User>> flowable = PagingRx.getFlowable(pager);
PagingRx.cachedIn(flowable, viewModelScope);

Java

// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
Pager<Integer, User> pager = Pager<>(
  new PagingConfig(/* pageSize = */ 20),
  () -> ExamplePagingSource(backend, query));

PagingLiveData.cachedIn(PagingLiveData.getLiveData(pager), 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 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.

PagedListAdapter

Bagian ini menjelaskan semua perubahan yang diperlukan untuk memigrasikan penerapan Paging versi lama agar dapat menggunakan class PagingDataAdapter atau AsyncPagingDataDiffer dari Paging 3.

Paging 3 menyediakan PagingDataAdapter untuk menangani aliran reaktif PagingData yang baru. Jika tidak ada, PagedListAdapter dan PagingDataAdapter akan memiliki antarmuka yang sama. Untuk bermigrasi dari PagedListAdapter ke PagingDataAdapter, ubah penerapan PagedListAdapter menjadi ekstensi PagingDataAdapter.

Untuk mempelajari PagingDataAdapter lebih lanjut, lihat Menetapkan adaptor RecyclerView.

AsyncPagedListDiffer

Jika Anda sedang menggunakan implementasi RecyclerView.Adapter kustom dengan AsyncPagedListDiffer, migrasikan penerapan agar dapat menggunakan AsyncPagingDataDiffer yang disediakan di Paging 3:

Kotlin

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Referensi lainnya

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

Codelab

Contoh