3. Sayfaya Taşı

Paging 3, Paging kitaplığının önceki sürümlerinden önemli ölçüde farklıdır. Bu sürüm; gelişmiş işlevsellik, Kotlin coroutine'leri ve Flow için birinci sınıf destek ve Jetpack Compose ile sorunsuz entegrasyon sunar.

Paging 3'e geçiş yapmanın avantajları

Paging 3, kitaplığın önceki sürümlerinde bulunmayan aşağıdaki özellikleri içerir:

  • Kotlin eş yordamları ve Flow için birinci sınıf destek.
  • Yeniden deneme ve yenileme işlevi de dahil olmak üzere duyarlı kullanıcı arayüzü tasarımı için yerleşik yükleme durumu ve hata sinyalleri.
  • İptal desteği ve basitleştirilmiş veri kaynağı arayüzü dahil olmak üzere depo katmanında iyileştirmeler.
  • Sunum katmanı, liste ayırıcıları, özel sayfa dönüştürmeleri, başlıklar ve altbilgiler ile geç yüklenen listeler için yükleme durumu öğelerinde iyileştirmeler yapıldı.

Uygulamanızı Paging 3'e taşıma

Paging 3'e tam olarak geçiş yapmak için Paging 2'deki şu önemli bileşenleri taşımanız gerekir:

  • DataSource sınıf
  • PagedList
  • Sunum katmanı (LazyPagingItems)

Ancak bazı Paging 3 bileşenleri, Paging'in önceki sürümleriyle geriye dönük olarak uyumludur. Özellikle Pager API, asPagingSourceFactory yöntemiyle daha eski DataSource nesnelerini kullanabilir. Bu durumda aşağıdaki taşıma seçenekleriniz vardır:

  • DataSource öğenizi PagingSource öğesine taşıyabilir ancak geri kalan sayfalama uygulamanızı değiştirmeden bırakabilirsiniz.
  • Uygulamanızı Paging 3'e tamamen taşımak için tüm Paging uygulamasını taşıyabilirsiniz.

Bu sayfadaki bölümlerde, uygulamanızın her katmanındaki Paging bileşenlerinin nasıl taşınacağı açıklanmaktadır.

DataSource sınıf

Bu bölümde, eski bir Sayfalandırma uygulamasını PagingSource kullanacak şekilde taşımak için gerekli tüm değişiklikler açıklanmaktadır.

Sayfalandırma 2'deki PageKeyedDataSource, PositionalDataSource ve ItemKeyedDataSource Sayfalandırma 3'te PagingSource API'sinde birleştirilir. Eski API sınıflarındaki yükleme yöntemlerinin tümü, PagingSource içinde tek bir load yönteminde birleştirilir. Eski API sınıflarının uygulamalarındaki yükleme yöntemlerinde mantığın büyük bir kısmı genellikle aynı olduğundan bu, kod tekrarını azaltır.

Tüm yükleme yöntemi parametreleri, Paging 3'te her yükleme türü için alt sınıflar içeren LoadParams kapalı sınıfıyla değiştirilir. load yönteminizdeki yük türleri arasında ayrım yapmanız gerekiyorsa LoadParams sınıfının hangi alt sınıfının iletildiğini kontrol edin: LoadParams.Refresh, LoadParams.Prepend veya LoadParams.Append.

PagingSource uygulama hakkında daha fazla bilgi edinmek için Veri kaynağı tanımlama başlıklı makaleyi inceleyin.

Anahtarları yenileme

PagingSource uygulamaları, yenilemelerin yüklenen sayfa verilerinin ortasından nasıl devam edeceğini tanımlamalıdır. Bunu yapmak için state.anchorPosition'ı en son erişilen dizin olarak kullanarak doğru başlangıç anahtarını eşlemek üzere getRefreshKey'ı uygulayın.

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

Dönüşümleri listeleme

Paging kitaplığının daha eski sürümlerinde, sayfalandırılmış verilerin dönüştürülmesi aşağıdaki yöntemlere dayanır:

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

Paging 3'te tüm dönüşümler PagingData üzerinde operatör olarak uygulanır. Sayfalandırılmış listenizi dönüştürmek için yukarıdaki listedeki yöntemlerden herhangi birini kullanıyorsanız yeni PagingSource ile Pager oluştururken dönüştürme mantığınızı DataSource konumundan PagingData konumuna taşımanız gerekir.

Sayfalandırma 3'ü kullanarak sayfalara ayrılmış verilere dönüşüm uygulama hakkında daha fazla bilgi edinmek için Veri akışlarını dönüştürme başlıklı makaleyi inceleyin.

PagedList

Bu bölümde, eski bir Paging uygulamasını Paging 3'te Pager ve PagingData kullanacak şekilde taşımak için gereken tüm değişiklikler açıklanmaktadır.

PagedListBuilder sınıf

PagingData, Paging 2'deki mevcut PagedList yerine geçer. PagingData sürümüne geçmek için aşağıdakileri güncellemeniz gerekir:

  • Sayfalama yapılandırması PagedList.Config konumundan PagingConfig konumuna taşındı.
  • Eski oluşturucu sınıfları tek bir Pager sınıfında birleştirildi.
  • Pager, .flow özelliğiyle gözlemlenebilir bir Flow<PagingData> öğesini kullanıma sunar.
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)

Paging 3'ü kullanarak PagingData nesnelerinin reaktif akışını ayarlama hakkında daha fazla bilgi edinmek için PagingData akışı oluşturma başlıklı makaleyi inceleyin.

Katmanlı kaynaklar için BoundaryCallback

Paging 3'te RemoteMediator, ağ ve veritabanından gelen sayfalama için işleyici olarak PagedList.BoundaryCallback yerine kullanılır.

Paging 3'te ağdan ve veritabanından sayfalama için RemoteMediator kullanma hakkında daha fazla bilgi edinmek üzere Android Paging Codelab'ine göz atın.

LazyPagingItems

Bu bölümde, eski bir Paging uygulamasının Paging 3'ten LazyPagingItems kullanacak şekilde taşınması için gerekli tüm değişiklikler açıklanmaktadır.

Paging 3, yeni collectAsLazyPagingItems akışını işlemek için PagingData sağlar. Sunum katmanınızı taşımak için paging-compose yapısını kullanın ve PagingData öğelerini toplayıp @Composable işlevlerinde görüntülemek için collectAsLazyPagingItems kullanın.

LazyPagingItems hakkında daha fazla bilgi edinmek için Sayfalandırılmış verileri yükleme ve görüntüleme başlıklı makaleyi inceleyin.

Liste karşılaştırma ve güncellemeleri

Şu anda özel liste karşılaştırma mantığı kullanıyorsanız uygulamanızı Paging 3'te sağlanan LazyPagingItems kullanacak şekilde taşıyın. Fark karşılaştırmanın düzgün şekilde yapıldığından emin olmak için tembel listenizde bir öğe anahtarı belirtin:

@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)
            }
        }
    }
}

Öğe anahtarları hakkında daha fazla bilgi için Öğe anahtarları başlıklı makaleyi inceleyin.

Yükleme durumları

Paging 3'te, yükleme durumları için üstbilgi veya altbilgi göstermek üzere ayrı bir bağdaştırıcıya ihtiyacınız yoktur. LazyPagingItems nesnesi, doğrudan LazyColumn içinde kontrol edebileceğiniz bir loadState özelliğini kullanıma sunar.

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())
        }
    }
}

Ek kaynaklar

Paging kitaplığı hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynaklara bakın:

Belgeler

İçeriği görüntüleme