Paging 3 para Kotlin: guia completo com exemplos práticos

1. O que é e para que serve

Paging 3 é uma biblioteca do Google para Android, escrita em Kotlin, que resolve um dos problemas mais comuns no desenvolvimento mobile: o carregamento paginado de dados (pagination). Quando você tem uma lista com milhares ou milhões de itens (como feed de notícias, mensagens em um chat ou produtos em um catálogo), carregar tudo de uma vez é inviável — isso causaria estouro de memória, travamento da interface e alto consumo de dados. O Paging 3 automatiza o processo de carregar dados em partes (páginas) conforme o usuário rola a lista.

A biblioteca é construída com princípios modernos: usa corrotinas Kotlin para operações assíncronas, Flow para atualização reativa de dados e se integra perfeitamente com Jetpack Compose e RecyclerView. Diferente das versões anteriores (Paging 2), o Paging 3 oferece uma arquitetura mais limpa, menos código repetitivo (boilerplate) e suporte nativo para tratamento de erros, atualização de dados e cache.

O principal valor do Paging 3 é que você escreve apenas a lógica de carregamento de uma página (por exemplo, uma chamada de API), e a biblioteca decide quando buscar a próxima página, como armazenar os dados em memória, como notificar o adaptador sobre mudanças e como lidar com estados de carregamento (carregando, erro, lista vazia). Isso economiza horas de desenvolvimento e torna o aplicativo estável mesmo ao lidar com conjuntos enormes de dados.

2. Instalação

Paging 3 é uma biblioteca para Android/Kotlin, então é instalada através do sistema de build Gradle, e não via pip ou npm. Adicione a dependência no arquivo build.gradle.kts (módulo app):

// build.gradle.kts (Module: app)
dependencies {
    // Biblioteca principal do Paging 3
    implementation("androidx.paging:paging-runtime-ktx:3.3.5")
    
    // Se estiver usando Jetpack Compose (opcional)
    implementation("androidx.paging:paging-compose:3.3.5")
    
    // Se estiver usando RxJava (opcional)
    implementation("androidx.paging:paging-rxjava3:3.3.5")
    
    // Para testes (opcional)
    testImplementation("androidx.paging:paging-common:3.3.5")
}

Após sincronizar o Gradle, a biblioteca está pronta para uso. A versão mínima do SDK é 21 (Android 5.0).

3. Início rápido — exemplo funcional mínimo

Vamos criar uma tela simples que carrega uma lista de números de 1 a 1000, com 20 itens por página. O exemplo tem três partes: fonte de dados (PagingSource), ViewModel e interface (RecyclerView).

Passo 1. PagingSource — fonte de dados

class NumberPagingSource : PagingSource<Int, Int>() {
    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, Int> {
        return try {
            // Define a chave da próxima página (se null, é o primeiro carregamento)
            val currentPage = params.key ?: 0
            val pageSize = params.loadSize  // geralmente 20
            
            // Gera os dados para a página atual
            val start = currentPage * pageSize
            val end = minOf(start + pageSize, 1000)
            val numbers = (start until end).toList()
            
            // Retorna o resultado com chaves para próxima e página anterior
            LoadResult.Page(
                data = numbers,
                prevKey = if (currentPage > 0) currentPage - 1 else null,
                nextKey = if (end < 1000) currentPage + 1 else null
            )
        } catch (e: Exception) {
            LoadResult.Error(e)
        }
    }
    
    // Retorna a chave para recarregar (geralmente null ou a primeira chave)
    override fun getRefreshKey(state: PagingState<Int, Int>): Int? = null
}

Passo 2. ViewModel

class MainViewModel : ViewModel() {
    val pager = Pager(
        config = PagingConfig(pageSize = 20, enablePlaceholders = f