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 e resolve problemas comuns com o uso da Paging 2. Caso seu app já use uma versão anterior da biblioteca Paging, leia esta página para saber mais sobre a migração para a Paging 3.

Se a Paging 3 for a primeira versão da biblioteca Paging que você está usando no app, consulte Carregar e mostrar dados paginados para informações básicas de uso.

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 fluxo do Kotlin.
  • Suporte a carregamento assíncrono usando primitivas Single do RxJava ou ListenableFuture do Guava.
  • 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 e carregamento de cabeçalhos e rodapés de estados.

Migrar seu app para a Paging 3

Para migrar totalmente para a Paging 3, será necessário migrar os três componentes principais da Paging 2:

  • Classes DataSource
  • PagedList
  • PagedListAdapter

No entanto, alguns componentes da Paging 3 são compatíveis com versões anteriores da Paging. Especificamente, a API PagingSource da Paging 3 pode ser uma fonte de dados para LivePagedListBuilder e RxPagedListBuilder de versões mais antigas. Da mesma forma, 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.
  • É possível migrar PagedList e PagedListAdapter, mas ainda usar a API DataSource mais antiga.
  • 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.

Kotlin

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

Java

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

  return state.getClosestItemToPosition(anchorPosition);
}

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

Java

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

  return state.getClosestItemToPosition(anchorPosition);
}

// Replacing PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
  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.
  • LivePagedListBuilder e RxPagedListBuilder foram combinados em uma única classe Pager.
  • Pager expõe um Flow<PagingData> observável com a propriedade .flow. As variantes RxJava e LiveData também estão disponíveis como propriedades de extensão, que podem ser chamadas do Java usando métodos estáticos e são fornecidas pelos módulos paging-rxjava* e paging-runtime, respectivamente.

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);

Para saber mais sobre como configurar um fluxo reativo de objetos PagingData 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.

PagedListAdapter

A paginação 2 usa PagedListAdapter para vincular um PagedList a um RecyclerView. No Paging 3, PagingData substitui PagedList. Se você estiver migrando seu app para usar o Jetpack Compose na interface, não vai precisar de um adaptador para mostrar dados paginados.

Em vez disso, use o artefato paging-compose e o método de extensão collectAsLazyPagingItems para coletar itens PagingData e mostrá-los em funções @Composable como LazyColumn.

Para mais informações sobre como usar a Paging 3 com o Jetpack Compose, consulte Visão geral da Paging 3.

Outros recursos

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

Codelabs

Exemplos