Effectuer une migration vers Paging 3

Paging 3 diffère considérablement des versions précédentes de la bibliothèque Paging. Cette version fournit des fonctionnalités améliorées, une prise en charge de premier ordre des coroutines Kotlin et de Flow, ainsi qu'une intégration transparente avec Jetpack Compose.

Avantages de la migration vers Paging 3

Paging 3 inclut les fonctionnalités suivantes, qui n'étaient pas présentes dans les versions précédentes de la bibliothèque :

  • Prise en charge de grande qualité des coroutines Kotlin et de Flow.
  • Indicateurs d'erreur et d'état de chargement intégrés pour la conception d'interface utilisateur responsive, y compris la fonctionnalité de nouvelle tentative et d'actualisation.
  • Améliorations apportées à la couche de dépôt, y compris la prise en charge de l'annulation et une interface de source de données simplifiée.
  • Améliorations apportées à la couche de présentation, aux séparateurs de liste et aux transformations de page personnalisées, ainsi qu'aux en-têtes et aux pieds de page et aux éléments d'état de chargement pour les listes paresseuses.

Migrer votre application vers Paging 3

Pour une migration complète vers Paging 3, vous devez migrer les principaux composants suivants de Paging 2 :

  • Classes DataSource
  • PagedList
  • Couche de présentation (vers LazyPagingItems)

Cependant, certains composants de Paging 3 sont rétrocompatibles avec les versions précédentes de Paging. En particulier, l'API Pager peut utiliser des objets plus anciens DataSource avec la méthode asPagingSourceFactory. Cela signifie que vous disposez des options de migration suivantes :

  • Vous pouvez migrer votre DataSource vers PagingSource, mais ne pas modifier le reste de votre implémentation Paging.
  • Vous pouvez migrer l'implémentation complète de Paging pour migrer entièrement votre application vers Paging 3.

Les sections de cette page expliquent comment migrer des composants Paging sur chaque couche de votre application.

Classes DataSource

Cette section décrit toutes les modifications nécessaires pour migrer une ancienne implémentation de Paging vers PagingSource.

Les PageKeyedDataSource, PositionalDataSource et ItemKeyedDataSource de Paging 2 sont tous combinés dans l'API PagingSource de Paging 3. Les méthodes de chargement de toutes les anciennes classes d'API sont regroupées dans une seule méthode load dans PagingSource. Cela réduit la duplication de code, car une grande partie de la logique entre les méthodes de chargement dans les implémentations des anciennes classes d'API est souvent identique.

Tous les paramètres de méthode de chargement sont remplacés dans Paging 3 par une classe scellée LoadParams, qui inclut des sous-classes pour chaque type de chargement. Si vous devez différencier les types de chargement de votre méthode load, vérifiez quelle sous-classe de LoadParams a été transmise : LoadParams.Refresh, LoadParams.Prepend ou LoadParams.Append.

Pour en savoir plus sur l'implémentation de PagingSource, consultez Définir une source de données.

Clés d'actualisation

Les implémentations de PagingSource doivent définir la manière dont les actualisations reprennent à partir du milieu des données paginées chargées. Pour ce faire, implémentez getRefreshKey pour mapper la clé initiale correcte en utilisant state.anchorPosition comme dernier index consulté.

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

Transformations de listes

Dans les versions inférieures de la bibliothèque Paging, la transformation des données paginées repose sur les méthodes suivantes :

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

Dans Paging 3, toutes les transformations sont appliquées en tant qu'opérateurs dans PagingData. Si vous utilisez l'une des méthodes de la liste précédente pour transformer votre liste paginée, vous devez déplacer votre logique de transformation depuis la DataSource vers les PagingData lors de la création du Pager à l'aide de votre nouvelle PagingSource.

Pour en savoir plus sur l'application de transformations aux données paginées à l'aide de Paging 3, consultez Transformer des flux de données.

PagedList

Cette section décrit toutes les modifications nécessaires pour migrer une ancienne implémentation de Paging afin d'utiliser Pager et PagingData dans Paging 3.

Classes PagedListBuilder

PagingData remplace la PagedList existante de Paging 2. Pour migrer vers PagingData, vous devez mettre à jour les éléments suivants :

  • La configuration de Paging a été déplacée de PagedList.Config vers PagingConfig.
  • Les anciennes classes de compilateur ont été combinées en une seule classe Pager.
  • Pager expose un élément observable Flow<PagingData> avec sa propriété .flow.
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)

Pour en savoir plus sur la configuration d'un flux réactif d'objets PagingData à l'aide de Paging 3, consultez Configurer un flux de PagingData.

BoundaryCallback pour les sources superposées

Dans Paging 3, RemoteMediator remplace PagedList.BoundaryCallback en tant que gestionnaire de la pagination depuis le réseau et la base de données.

Pour en savoir plus sur l'utilisation de RemoteMediator pour parcourir les pages du réseau et de la base de données dans Paging 3, consultez l'atelier de programmation Android Paging.

LazyPagingItems

Cette section décrit toutes les modifications nécessaires pour migrer une ancienne implémentation de Paging afin d'utiliser LazyPagingItems de Paging 3.

Paging 3 fournit collectAsLazyPagingItems pour gérer le nouveau flux PagingData. Pour migrer votre couche de présentation, utilisez l'artefact paging-compose et collectAsLazyPagingItems pour collecter les éléments PagingData et les afficher dans les fonctions @Composable.

Pour en savoir plus sur LazyPagingItems, consultez Charger et afficher des données paginées.

Différences et mises à jour de listes

Si vous utilisez actuellement une logique de différence de liste personnalisée, migrez votre implémentation pour qu'elle utilise la valeur LazyPagingItems fournie dans Paging 3. Pour vous assurer que la différence est correcte, spécifiez une clé d'élément dans votre liste paresseuse :

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

Pour en savoir plus sur les clés d'élément, consultez Clés d'élément.

États de chargement

Dans Paging 3, vous n'avez pas besoin d'un adaptateur distinct pour afficher les en-têtes ou les pieds de page pour les états de chargement. L'objet LazyPagingItems expose une propriété loadState que vous pouvez vérifier directement dans votre 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())
        }
    }
}

Ressources supplémentaires

Pour en savoir plus sur la bibliothèque Paging, consultez ces ressources supplémentaires :

Documentation

Afficher le contenu