O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Paging

A Biblioteca Paging facilita o carregamento gradual e tranquilo de dados no RecyclerView do seu app.
Atualização mais recente Versão estável atual Próximo candidato a lançamento Versão Beta Versão Alfa
2 de setembro de 2020 2.1.2 - - 3.0.0-alpha06

Declarar dependências

Para adicionar uma dependência à Paging, é preciso adicionar o repositório Maven do Google ao seu projeto. Leia Repositório Maven do Google para ver mais informações.

Adicione as dependências dos artefatos necessários no arquivo build.gradle para seu app ou módulo:

    dependencies {
      def paging_version = "2.1.2"

      implementation "androidx.paging:paging-runtime:$paging_version" // For Kotlin use paging-runtime-ktx

      // alternatively - without Android dependencies for testing
      testImplementation "androidx.paging:paging-common:$paging_version" // For Kotlin use paging-common-ktx

      // optional - RxJava support
      implementation "androidx.paging:paging-rxjava2:$paging_version" // For Kotlin use paging-rxjava2-ktx
    }
    

Para ver mais informações sobre o uso de extensões Kotlin, consulte a documentação do Android KTX.

Como alternativa, você pode testar a versão Alfa da Paging 3.0. Para usar o Paging 3.0, adicione as seguintes dependências ao arquivo build.gradle:

dependencies {
  def paging_version = "3.0.0-alpha06"

  implementation "androidx.paging:paging-runtime:$paging_version"

  // alternatively - without Android dependencies for tests
  testImplementation "androidx.paging:paging-common:$paging_version"

  // optional - RxJava2 support
  implementation "androidx.paging:paging-rxjava2:$paging_version"

  // optional - Guava ListenableFuture support
  implementation "androidx.paging:paging-guava:$paging_version"
}

Para ver mais informações sobre dependências, consulte Adicionar dependências de compilação.

Feedback

Seu feedback ajuda a melhorar o Jetpack. Avise se você descobrir novos problemas ou tiver ideias para melhorar esta biblioteca. Consulte os problemas existentes nesta biblioteca antes de criar um novo. Adicione seu voto a um problema existente clicando no botão de estrela.

Criar novo problema (link em inglês)

Consulte a documentação do Issue Tracker para saber mais.

Versão 3.0.0

Versão 3.0.0-alpha06

2 de setembro de 2020

Lançamento do androidx.paging:paging-*:3.0.0-alpha06. A versão 3.0.0-alpha06 contém essas confirmações.

Mudanças na API

  • UnsupportedOperationException com mensagens mais claras sobre a falta de suporte para IDs estáveis é gerada sempre que PagingDataAdapter.setHasStableIds é chamado. Ib3890, b/158801427

Correções de bugs

  • O insertSeparators não filtra mais páginas vazias, permitindo que a distância de pré-busca seja respeitada pelo apresentador, mesmo nos casos em que muitas páginas vazias são inseridas. I9cff6, b/162538908

Versão 3.0.0-alpha05

19 de agosto de 2020

androidx.paging:paging-*:3.0.0-alpha05 é lançado. A versão 3.0.0-alpha05 contém essas confirmações.

Correções de bugs

  • Paging agora faz a pré-busca correta das páginas, mesmo quando os dados apresentados são muito filtrados.
  • O retorno de LoadResult.Error a uma carga repetida não faz mais com que os acessos ao item acionem incorretamente uma nova tentativa.

Contribuição externa

  • Agradecemos a Clara F por ajudar a limpar alguns testes. (549612).

Versão 3.0.0-alpha04

5 de agosto de 2020

androidx.paging:paging-*:3.0.0-alpha04 é lançada. A versão 3.0.0-alpha04 contém essas confirmações (link em inglês).

Mudanças na API

  • Adição da API peek() a AsyncPagingDataDiffer e PagingDataAdapter para permitir o acesso a dados apresentados sem acionar carregamentos de página. (I38898, b/159104197)
  • Adição da API snapshot() a PagingDataAdapter e AsyncPagingDataDiffer para permitir a recuperação dos itens apresentados sem acionar a busca da página. (I566b6, b/159104197)
  • Adição de um construtor PagingData.from(List<T>) para permitir a apresentação de listas estáticas, que podem ser combinadas com o fluxo geral de PagingData para mostrar listas estáticas em determinados estados, por exemplo, antes da conclusão de REFRESH inicial ou simplesmente para testar transformações. (Id134d)
  • Suspensão do uso das APIs Flow / Listener de dataRefresh porque se destinavam a expor o estado de itens apresentados em REFRESH, mas com melhorias para o tempo de callback de Flow / Listener de loadState e, para a propriedade itemCount, é redundante (Ia19f3).
  • Adição de wrappers de compatibilidade RxJava3 para PagingSource e RemoteMediator (I49ef3, b/161480176).

Correções de bugs

  • PositionalDataSource convertido em PagingSource por meio do auxiliar toPagingSourceFactory, incluindo PagingSource gerado por Room agora se marca corretamente para dar suporte a saltos. (I3e84c, b/162161201)
  • Correção de um bug em que o uso da variante síncrona de submitData às vezes levava a uma disputa, causando um ClosedSendChannelException (I4d702, b/160192222).

Contribuição externa

  • Agradecemos a Zac Sweers por adicionar wrappers de compatibilidade RxJava3 em nome do Slack (I49ef3, b/161480176).

Versão 3.0.0-alpha03

22 de julho de 2020

Lançamento do androidx.paging:paging-*:3.0.0-alpha03. A versão 3.0.0-alpha03 contém essas confirmações (link em inglês).

Mudanças na API

  • O construtor do PagingState agora é público, o que facilitará as implementações de teste de getRefreshKey() (I8bf15, link em inglês)
  • No Java, variantes de função de mapa do Kotlin do DataSource são ocultas para resolver ambiguidades entre variantes originais e do Kotlin. (If7b23, b/161150011, links em inglês)
  • As APIs redundantes criadas como conveniências para usuários do Kotlin foram marcadas como @JvmSynthetic (I56ae5, link em inglês)
  • Adição de sobrecargas para o construtor da LoadResult.Page, que tem o padrão de itemsBefore e itemsAfter definido como COUNT_UNDEFINED (I47849, link em inglês)
  • Operadores PagingData existentes agora aceitam métodos de suspensão e introduzem novos operadores mapSync, flatMapSync e filterSync sem suspensão para usuários do Java. Os métodos de transformação existentes foram movidos para as funções de extensão. Por isso, agora os usuários do Kotlin precisarão importá-los. (I34239, b/159983232, links em inglês)

Correções de bugs

  • Agora, PagingSources da Room (e PositionalDataSource) exibirão um separador inicial como parte da primeira página. Assim, o usuário não precisará rolar para vê-lo. (I6f747, b/160257628, links em inglês)
  • Os acessos a itens em marcadores agora acionam corretamente carregamentos PagingSource até que uma página que atenda ao índice solicitado seja preenchida depois de ser transformada pelo PagingData.filter() (I95625, b/15767619, links em inglês)
  • Correção de um bug em que, às vezes, a rolagem depois que PaginSource retorna um erro pode impedir que o PagingDataAdapter.retry() tente novamente. (I1084f, b/160194384, links em inglês)
  • Correção de um problema em que os acessos a um item depois que uma página é suspensa podem não carregar páginas, embora o acesso estivesse dentro da prefetchDistance (Ie95ae, b/160038730, links em inglês)
  • A configuração do PagingConfig.maxSize não permite mais marcadores após um evento de suspensão (I2be29, b/159667766, links em inglês)

Versão 3.0.0-alpha02

24 de junho de 2020

Lançamento do androidx.paging:paging-*:3.0.0-alpha02. A versão 3.0.0-alpha02 contém essas confirmações (link em inglês).

Mudanças na API

  • Adição de sobrecargas para o construtor de PagingConfig com valores padrão comuns (I39c50, b/158576040, links em inglês)
  • Adição de sobrecargas para construtores de PagingDataAdapter e AsyncPagingDataDiffer com valores padrão comuns (Ie91f5, link em inglês)
  • As APIs do adaptador, dataRefreshFlow e dataRefreshListener, agora passam um booleano para sinalizar se um PagingData está vazio (I6e37e, b/159054196, links em inglês).
  • Adição de APIs RxJava e Guava para RemoteMediator: RxRemoteMediator e ListenableFutureRemoteMediator
  • Adição de auxiliares ao PagingState para acesso a itens comuns, como isEmpty() e firstItemOrNull() (I3b5b6, b/158892717, links em inglês).

Correções de bugs

  • Agora, o Pager verifica a reutilização do PagingSource na fábrica para evitar a reutilização acidental de PagingSources inválidos, o que gerou um erro pouco claro (I99809, b/15486430, links em inglês).
  • As falhas do RemoteMediator REFRESH não impedem mais o carregamento do PagingSource (I38b1b, b/158892717, links em inglês).
  • A versão sem suspensão de submitData não causa mais uma falha devido à coleta simultânea em vários PagingData quando chamada após a versão de suspensão de submitData (I26358, b/158048877, links em inglês).
  • Correção da exceção "Não é possível coletar duas vezes a partir do pager", que poderia ocorrer após a mudança da configuração (I58bcc, b/158784811, links em inglês).

Versão 3.0.0-alpha01

10 de junho de 2020

androidx.paging:paging-*:3.0.0-alpha01 é lançada. A versão 3.0.0-alpha01 contém essas confirmações (link em inglês).

A biblioteca Paging foi atualizada para a versão 3.0 para ativar vários novos recursos importantes.

Novos recursos da versão 3.0

Problemas conhecidos

  • Os javadocs da Paging 3 ainda não estão disponíveis. Enquanto isso, use os guias vinculados acima ou os documentos do Kotlin. (b/158614050, link em inglês)

Versão 2.1.2

Versão 2.1.2

18 de março de 2020

Lançamento da androidx.paging:paging:2.1.2. A versão 2.1.2 contém essas confirmações contra a 2.1.0 (link em inglês).

Correções de bugs

  • Correção para IndexOutOfBoundsException em casos raros ao converter uma posição durante a invalidação.

Problema da versão

  • A versão 2.1.1 da Paging foi lançada incorretamente de uma ramificação configurada incorretamente, expondo APIs parcialmente implementadas e funcionalidades futuras de uma próxima versão.

  • A Paging 2.1.2 contém a correção de centralização de carga lançada originalmente na versão 2.1.1, mas desta vez escolhida corretamente na versão 2.1.0. É altamente recomendável fazer upgrade para essa versão, caso você esteja usando a versão 2.1.1 no momento.

Versão 2.1.1

Versão 2.1.1

18 de dezembro de 2019

Lançamento do androidx.paging:paging-*:2.1.1. A versão 2.2.1 contém essas confirmações (link em inglês).

Correções de bugs

  • Os carregamentos iniciais contíguos de PositionalDataSources agora estão centralizados no último acesso quando os marcadores estão desativados.

Versão 2.1.0

Versão 2.1.0

25 de janeiro de 2019

Lançamento da Paging 2.1.0 sem mudanças de 2.1.0-rc01.

Versão 2.1.0-rc01

6 de dezembro de 2018

Lançamento da Paging 2.1.0-rc01 sem mudanças de 2.1.0-beta01.

Versão 2.1.0-beta01

1º de novembro de 2018

Lançamento da Paging 2.1.0-beta01 sem mudanças de 2.1.0-alpha01.

Versão 2.1.0-alpha01

12 de outubro de 2018

A Paging 2.1.0-alpha01 tem duas adições importantes: descarte de página e bibliotecas de extensões KTX para cada artefato, além de várias outras alterações de API e correções bugs.

Mudanças na API

  • Adição de PagedList.Config.Builder.setMaxSize() para limitar o número de itens carregados na memória.
  • Adição de androidx.paging.Config() como alternativa Kotlin para PagedList.Config.Builder.
  • Adição de androidx.paging.PagedList() como alternativa Kotlin para PagedList.Builder.
  • Adição de DataSourceFactory.toLiveData() como alternativa Kotlin para LivePagedListBuilder.
  • Adição de DataSourceFactory.toObservable() e toFlowable() como alternativas Kotlin para RxPagedListBuilder.
  • Adição de AsyncPagedListDiffer.addPagedListListener() para ouvir quando a PagedList foi trocada. b/111698609 (link em inglês)
  • Adição de variante PagedListAdapter.onCurrentListChanged() que transmite a lista antiga e a nova. A variante anterior teve o uso suspenso.
  • Adição de variantes PagedListAdapter/AsyncPagedListDiffer.submitList() que recebem um callback extra que é acionado se/quando a pagedlist é exibida, depois da diferenciação. Isso permite que você sincronize uma troca de PagedList com outras atualizações da IU. b/73781068 (link em inglês)
  • Adição de PagedList.getLoadedCount() para informar quantos itens estão na memória. Observe que o valor de retorno será sempre igual a .size() se os marcadores estiverem desativados.

Correções de bugs

  • Correção de uma disputa ao diferenciar se as listas são reutilizadas. b/111591017 (link em inglês)
  • PagedList.loadAround() agora gera IndexOutOfBoundsException quando o índice é inválido. Anteriormente, ele poderia falhar com uma exceção diversa incerta.
  • Correção de um caso em que um tamanho de carga inicial extremamente pequeno junto com dados inalterados resultava em nenhum outro carregamento b/113122599 (link em inglês).

Versão 2.0.0

Versão 2.0.0

1º de outubro de 2018

A Paging 2.0.0 foi lançada com uma única correção de bug.

Correções de bugs

  • Correção de uma falha que poderia ocorrer com rolagem muito rápida usando PositionalDataSource e marcadores. b/114635383 (link em inglês).

Versão 2.0.0-beta01

2 de julho de 2018

Correções de bugs

  • Correção de conteúdo ausente em alguns casos de prefixo (marcadores de posição desativados, PositionalDataSource). b/80149146 (link em inglês)
  • Já lançado em 1.0.1. Correção de falhas em que PagedListAdapter e AsyncPagedListDiffer não sinalizavam eventos de movimentação. b/110711937 (link em inglês)

Dependências anteriores ao AndroidX

Para as seguintes versões da Paging anteriores ao AndroidX, inclua estas dependências:

dependencies {
    def paging_version = "1.0.0"

    implementation "android.arch.paging:runtime:$paging_version"

    // alternatively - without Android dependencies for testing
    testImplementation "android.arch.paging:common:$paging_version"

    // optional - RxJava support
    implementation "android.arch.paging:rxjava2:$paging_version"
}

Versão 1.0.1

Versão 1.0.1

26 de junho de 2018

A Paging 1.0.1 foi lançada com uma única correção de bug em runtime. É altamente recomendável usar a 1.0.1 por questão de estabilidade. Paging RxJava2 1.0.1 também foi liberada e é idêntica à 1.0.0-rc1.

Correções de bugs

  • Correção de falhas em que PagedListAdapter e AsyncPagedListDiffer não sinalizavam eventos de movimentação. b/110711937 (link em inglês)

RxJava2 versão 1.0.0

RxJava2 Versão 1.0.0-rc1

16 de maio de 2018

A Paging 1.0.0-rc1 RxJava2 está progredindo para se tornar candidata a lançamento sem mudanças desde a versão Alfa inicial.

Versão 1.0.0

Versão 1.0.0-rc1

19 de abril de 2018 Candidata a lançamento da Paging

Não temos outros problemas conhecidos ou novos recursos programados para a Paging versão 1.0.0. Faça upgrade dos seus projetos para usar 1.0.0-rc1 e ajude a testá-la para que possamos lançar uma versão 1.0.0 sólida.

Não há mudanças nessa versão. Ela é a mesma que 1.0.0-beta1.

Versão 1.0.0-beta01

5 de abril de 2018

A Paging ficará na versão Beta por um breve período antes de progredir para candidata a lançamento. Não estamos planejando outras mudanças na API para a Paging 1.0, e a resistência a qualquer mudança na API é muito alta.

A compatibilidade do RxJava2 Alfa com a Paging foi lançada como um módulo opcional diferente (android.arch.paging:rxjava2:1.0.0-alpha1), e a versão dela será temporariamente controlada em separado até ela se estabilizar.

Essa nova biblioteca traz uma alternativa à RxJava2 para LivePagedListBuilder, capaz de construir Observables e Flowables, usando Schedulers em vez de Executors:

Kotlin

val pagedItems = RxPagedListBuilder(myDataSource, /* page size */ 50)
        .setFetchScheduler(myNetworkScheduler)
        .buildObservable()

Java

Observable<PagedList<Item>> pagedItems =
        RxPagedListBuilder(myDataSource, /* page size */ 50)
                .setFetchScheduler(myNetworkScheduler)
                .buildObservable();

Novos recursos

  • Adição de RxPagedListBuilder por meio do novo artefato android.arch.paging:rxjava2.

Mudanças na API

  • Mudanças de API para esclarecer o papel dos executores em builders:

    • setBackgroundThreadExecutor() renomeado para setFetchExecutor() (em PagedList.Builder e LivePagedListBuilder)

    • setMainThreadExecutor() renomeado para setNotifyExecutor() (em PagedList.Builder).

  • Correção do membro PagedList.mCallbacks para que seja privado.

Correções de bugs

  • LivePagedListBuilder aciona o carregamento inicial de PagedList no executor especificado, em vez do pool de linhas de execução de IO dos Componentes de arquitetura.

  • Correção do comportamento de invalidação em wrappers DataSource internos, usados para implementar o DataSource.map, bem como o carregamento de PositionalDataSource com marcadores desativados. b/77237534 (link em inglês)

Versão 1.0.0-alpha7

21 de março de 2018

Lançamento da Paging 1.0.0-alpha7 junto com Lifecycles 1.1.1. Como Paging alpha7 depende do movimento da classe Function mencionada acima, você precisará atualizar sua dependência de lifecycle:runtime para android.arch.lifecycle:runtime:1.1.1.

A Paging alpha7 está sendo planejada para ser a versão final antes de chegar à versão beta.

Mudanças na API

  • Os objetos DataSource.LoadParams agora têm um construtor público e os objetos DataSource.LoadCallback agora são abstratos. Isso permite realizar o wrapper de DataSource ou testar diretamente um DataSource com um callback simulado. b/72600421 (link em inglês).
  • Mapeadores para DataSource e DataSource.Factory
    • map(Function<IN,OUT>) permite que você transforme, una ou decore resultados carregados por um DataSource.
    • mapByPage(<List<IN>,List<OUT>>) proporciona o mesmo para o processamento em lote. Por exemplo, se os itens carregados do SQL precisarem consultar também um banco de dados separado, isso poderá ser feito em lote.
  • PagedList#getDataSource() é adicionado como um método de conveniência. b/72611341 (link em inglês)
  • Todas as classes obsoletas foram removidas da API, incluindo os elementos remanescentes do pacote recyclerview.extensions e o LivePagedListProvider.
  • DataSource.Factory é modificado de uma interface para uma classe abstrata para ativar a funcionalidade do mapa.

Correções de bugs

  • Builders foram alterados para serem finais. b/70848565 (link em inglês)
  • A implementação de DataSource da Room agora foi corrigida para processar consultas de várias tabelas. Essa correção está na Room 1.1.0-beta1, veja acima.
  • Correção de um bug em que o BoundaryCallback.onItemAtEndLoaded não seria invocado para PositionalDataSource se os marcadores estivessem ativados e o tamanho total fosse um múltiplo exato do tamanho da página.

Versão 1.0.0-alpha5

22 de janeiro de 2018

Correções de bugs

  • Correção do carregamento de página quando os marcadores de posição estão desativados. b/70573345 (link em inglês)
  • Criação de registros adicionais para rastrear o bug IllegalArgumentException. b/70360195 (e suposta correção do lado da Room)
  • Correções de código de amostra Javadoc. b/70411933, b/71467637 (links em inglês)