O SmartRefreshLayout é uma bilbioteca flexível e extensível para Android que fornece funcionalidades de pull-to-refresh e load-more (infinite scroll). Ela suporta uma variedade de views roláveis como RecyclerView e ListView, e vem com múltiplos estilos visuais para os indicadores de carregamento.

Adicionando a Dependência

Para começar, adicione as dependências necessárias ao seu arquivo build.gradle do módulo da aplicação.

implementation 'io.github.scwang90:refresh-layout-kernel:2.1.0'
implementation 'io.github.scwang90:refresh-header-classics:2.1.0'
implementation 'io.github.scwang90:refresh-footer-classics:2.1.0'

Caso o projeto utilize AndroidX, é necessário habiliatr a compatibilidade nas configurações do Gradle.

Configuração no Layout XML

Envolva a sua view rolável (por exemplo, RecyclerView) com o SmartRefreshLayout no arquivo de layout XML.

<com.scwang.smart.refresh.layout.SmartRefreshLayout
    android:id="@+id/swipeRefreshContainer"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:srlPrimaryColor="#3F51B5"
    app:srlAccentColor="#FFFFFF">

    <com.scwang.smart.refresh.header.ClassicsHeader
        android:layout_width="match_parent"
        android:layout_height="wrap_content"/>

    <androidx.recyclerview.widget.RecyclerView
        android:id="@+id/dataRecyclerView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

    <com.scwang.smart.refresh.footer.ClassicsFooter
        android:layout_width="match_parent"
        android:layout_height="wrap_content"/>

</com.scwang.smart.refresh.layout.SmartRefreshLayout>

Interação via Código (Kotlin/Java)

Após configurar o layout, obtenha a referência para o SmartRefreshLayout e defina os listeners para as ações de refresh e load-more.

val refreshContainer: SmartRefreshLayout = findViewById(R.id.swipeRefreshContainer)

// Configurar a ação de atualizar (pull-down)
refreshContainer.setOnRefreshListener { layout ->
    // Lógica para buscar novos dados
    fetchLatestItems()
    // Indicar que a operação foi concluída após 1.5 segundos
    layout.finishRefresh(1500L)
}

// Configurar a ação de carregar mais itens (pull-up)
refreshContainer.setOnLoadMoreListener { layout ->
    // Lógica para carregar a próxima página de dados
    loadNextPageOfData()
    // Indicar o fim do carregamento
    layout.finishLoadMore(1500L)
}

// Opcionalmente, desabilitar o load-more se não houver mais páginas
// refreshContainer.setEnableLoadMore(false)

Problemas Comuns e Soluções

O Refresh Não é Acionado: Verifique se a dependência foi sincronizada corretamente e se o SmartRefreshLayout é o pai direto da view rolável.

Load-more Não Funciona: Certifique-se de que a funcionalidade está habilitada com setEnableLoadMore(true). O framwork também oferece setEnableAutoLoadMore(true) para acionamento automático ao rolar para o fim da lista.

Header ou Footer Personalizado Não Aparece: Ao criar um componente personalizado (implementando RefreshHeader ou RefreshFooter), ele deve ser corretamente atribuído via método setRefreshHeader(myCustomHeader) ou declarado diretamente no XML.

Recursos Avançados

O framework permite criar experiências complexas, como o efeito de "segundo andar" (two-level refresh). Para isso, basta registrar um listener específico.

refreshContainer.setOnTwoLevelListener { layout ->
    // Ação para abrir uma tela secundária, similar ao "Taobao Second Floor"
    openPromotionScreen()
    layout.finishRefresh(3000L)
}

Para alterar o estilo visual globalmente, é possível definir um criador padrão de header para toda a aplicação.

SmartRefreshLayout.setDefaultRefreshHeaderCreator { context, layout ->
    layout.setPrimaryColorsId(R.color.primary, android.R.color.white)
    ClassicsHeader(context)
}

O SmartRefreshLayout também suporta o efeito de overscroll bounce em todas as views roláveis, proporcionando uma experiência de rolagem mais fluida em dispositivos com Android recente.