Migrar para a Paging 3

A Paging 3 tem diferenças significativas em relação às versões anteriores da biblioteca Paging. Essa versão oferece funcionalidades aprimoradas, suporte de primeira classe para corrotinas e Flow do Kotlin e integração perfeita com o Jetpack Compose.

Benefícios da migração para a Paging 3

A Paging 3 inclui os seguintes recursos que não estavam presentes em versões anteriores da biblioteca:

  • Suporte de primeira classe a corrotinas e Flow do Kotlin.
  • Sinais de erro e estado de carregamento integrados para design de IU responsivo, incluindo as funcionalidades tentar novamente e atualizar.
  • Melhorias na camada de repositório, incluindo compatibilidade com cancelamento e uma interface de fonte de dados simplificada.
  • Melhorias na camada de apresentação, separadores de lista, transformações de página personalizadas, cabeçalhos e rodapés e itens de estado de carregamento para listas lentas.

Migrar seu app para a Paging 3

Para migrar totalmente para a Paging 3, será necessário migrar estes componentes principais da Paging 2:

  • Classes DataSource
  • PagedList
  • Camada de apresentação (para LazyPagingItems)

No entanto, alguns componentes da Paging 3 são compatíveis com versões anteriores da Paging. Em particular, a API Pager pode usar objetos DataSource mais antigos com o método asPagingSourceFactory. Isso significa que você tem as seguintes opções de migração:

  • Você pode migrar a DataSource para PagingSource, mas não mudar o restante da implementação da Paging.
  • Você pode migrar toda a implementação da Paging para migrar totalmente seu app para a Paging 3.

As seções desta página explicam como migrar os componentes da Paging em cada camada do app.

Classes DataSource

Esta seção descreve todas as mudanças necessárias para migrar uma implementação antiga da Paging para usar PagingSource.

Os valores PageKeyedDataSource, PositionalDataSource e ItemKeyedDataSource da Paging 2 são combinados na API PagingSource na Paging 3. Os métodos de carregamento de todas as classes de API antigas são combinados em um único método load em PagingSource. Isso reduz a duplicação de código, porque grande parte da lógica entre os métodos de carregamento nas implementações das classes antigas da API costuma ser idêntica.

Todos os parâmetros do método de carregamento são substituídos na Paging 3 por uma classe selada LoadParams, que inclui subclasses para cada tipo de carregamento. Se você precisar diferenciar os tipos de carregamento no método load, verifique qual subclasse de LoadParams foi transmitida: LoadParams.Refresh, LoadParams.Prepend ou LoadParams.Append.

Para saber mais sobre como implementar PagingSource, consulte Definir uma fonte de dados.

Atualizar chaves

As implementações de PagingSource precisam definir como as atualizações são retomadas do meio dos dados paginados. Para isso, implemente getRefreshKey para mapear a chave inicial correta usando state.anchorPosition como o índice acessado mais recentemente.

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

Listar transformações

Nas versões mais antigas da biblioteca Paging, a transformação dos dados paginados depende dos seguintes métodos:

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

Na Paging 3, todas as transformações são aplicadas como operadores em PagingData. Se você usar qualquer um dos métodos da lista anterior para transformar sua lista paginada, precisará mover a lógica de transformação da DataSource para PagingData ao construir o Pager usando a nova PagingSource.

Para saber mais sobre como aplicar transformações a dados paginados usando a Paging 3, consulte Transformar fluxos de dados.

PagedList

Esta seção descreve todas as mudanças necessárias para migrar uma implementação mais antiga da Paging para usar Pager e PagingData na Paging 3.

Classes PagedListBuilder

PagingData substitui a PagedList da Paging 2. Para migrar para PagingData, é preciso atualizar o seguinte:

  • A configuração de paginação foi movida de PagedList.Config para PagingConfig.
  • As classes de builder mais antigas foram combinadas em uma única classe Pager.
  • Pager expõe um Flow<PagingData> observável com a propriedade .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)

Para saber mais sobre como configurar um fluxo reativo de PagingData objetos usando a Paging 3, consulte Configurar um fluxo de PagingData.

BoundaryCallback para origens em camadas

Na Paging 3, RemoteMediator substitui PagedList.BoundaryCallback como um gerenciador para paginação pela rede e pelo banco de dados.

Para saber mais sobre o uso do RemoteMediator para paginar pela rede e pelo banco de dados na Paging 3, consulte o codelab da Android Paging.

LazyPagingItems

Esta seção descreve todas as mudanças necessárias para migrar uma implementação mais antiga da Paging para usar LazyPagingItems da Paging 3.

A Paging 3 fornece collectAsLazyPagingItems para lidar com o novo fluxo PagingData. Para migrar a camada de apresentação, use o artefato paging-compose e collectAsLazyPagingItems para coletar itens PagingData e mostrá-los em funções @Composable.

Para saber mais sobre LazyPagingItems, consulte Carregar e mostrar dados paginados.

Diferenciação e atualizações de listas

Se você usa atualmente uma lógica de diferenciação de lista personalizada, migre-a para usar LazyPagingItems, fornecida na Paging 3. Para garantir que a diferenciação aconteça corretamente, especifique uma chave de item na lista lenta:

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

Para mais informações sobre chaves de item, consulte Chaves de item.

Estados de carregamento

Na Paging 3, não é necessário um adaptador separado para mostrar cabeçalhos ou rodapés para estados de carregamento. O objeto LazyPagingItems expõe uma propriedade loadState que pode ser verificada diretamente na 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())
        }
    }
}

Outros recursos

Para saber mais sobre a biblioteca Paging, consulte os seguintes recursos extras:

Documentação

Conteúdo de visualizações