Visualizza elenchi impaginati

Questo documento si basa sulla panoramica della libreria Paging e descrive come puoi presentare elenchi di informazioni agli utenti nella UI della tua app, in particolare quando queste informazioni cambiano.

Collega la UI al modello di visualizzazione

Puoi connettere un'istanza di LiveData<PagedList> a un PagedListAdapter, come mostrato nello snippet di codice seguente:

Kotlin

class ConcertActivity : AppCompatActivity() {
    private val adapter = ConcertAdapter()

    // Use the 'by viewModels()' Kotlin property delegate
    // from the activity-ktx artifact
    private val viewModel: ConcertViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState);
        viewModel.concerts.observe(this, Observer { adapter.submitList(it) })
    }
}

Java

public class ConcertActivity extends AppCompatActivity {
    private ConcertAdapter adapter = new ConcertAdapter();
    private ConcertViewModel viewModel;

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        viewModel = new ViewModelProvider(this).get(ConcertViewModel.class);
        viewModel.concertList.observe(this, adapter::submitList);
    }
}

Man mano che le origini dati forniscono nuove istanze di PagedList, l'attività invia questi oggetti all'adattatore. L'implementazione di PagedListAdapter definisce il modo in cui vengono calcolati gli aggiornamenti e gestisce automaticamente l'impaginazione e il diffing degli elenchi. Pertanto, il tuo ViewHolder deve essere associato solo a un particolare elemento fornito:

Kotlin

class ConcertAdapter() :
        PagedListAdapter<Concert, ConcertViewHolder>(DIFF_CALLBACK) {
    override fun onBindViewHolder(holder: ConcertViewHolder, position: Int) {
        val concert: Concert? = getItem(position)

        // Note that "concert" is a placeholder if it's null.
        holder.bindTo(concert)
    }

    companion object {
        private val DIFF_CALLBACK = ... // See Implement the diffing callback section.
    }
}

Java

public class ConcertAdapter
        extends PagedListAdapter<Concert, ConcertViewHolder> {
    protected ConcertAdapter() {
        super(DIFF_CALLBACK);
    }

    @Override
    public void onBindViewHolder(@NonNull ConcertViewHolder holder,
            int position) {
        Concert concert = getItem(position);

        // Note that "concert" can be null if it's a placeholder.
        holder.bindTo(concert);
    }

    private static DiffUtil.ItemCallback<Concert> DIFF_CALLBACK
            = ... // See Implement the diffing callback section.
}

PagedListAdapter gestisce gli eventi di caricamento pagina utilizzando un oggetto PagedList.Callback. Mentre l'utente scorre, PagedListAdapter chiama PagedList.loadAround() per fornire suggerimenti a PagedList sottostante su quali elementi recuperare da DataSource.

Implementa il callback di differenziazione

L'esempio seguente mostra un'implementazione manuale di areContentsTheSame(), che confronta i campi degli oggetti pertinenti:

Kotlin

private val DIFF_CALLBACK = object : DiffUtil.ItemCallback<Concert>() {
    // The ID property identifies when items are the same.
    override fun areItemsTheSame(oldItem: Concert, newItem: Concert) =
            oldItem.id == newItem.id

    // If you use the "==" operator, make sure that the object implements
    // .equals(). Alternatively, write custom data comparison logic here.
    override fun areContentsTheSame(
            oldItem: Concert, newItem: Concert) = oldItem == newItem
}

Java

private static DiffUtil.ItemCallback<Concert> DIFF_CALLBACK =
        new DiffUtil.ItemCallback<Concert>() {

    @Override
    public boolean areItemsTheSame(Concert oldItem, Concert newItem) {
        // The ID property identifies when items are the same.
        return oldItem.getId() == newItem.getId();
    }

    @Override
    public boolean areContentsTheSame(Concert oldItem, Concert newItem) {
        // Don't use the "==" operator here. Either implement and use .equals(),
        // or write custom data comparison logic here.
        return oldItem.equals(newItem);
    }
};

Poiché l'adattatore include la tua definizione di confronto degli elementi, l'adattatore rileva automaticamente le modifiche a questi elementi quando viene caricato un nuovo oggetto PagedList. Di conseguenza, l'adattatore attiva animazioni efficienti degli elementi all'interno dell'oggetto RecyclerView.

Diffing utilizzando un tipo di adattatore diverso

Se scegli di non ereditare da PagedListAdapter, ad esempio quando utilizzi una libreria che fornisce il proprio adattatore, puoi comunque utilizzare la funzionalità di differenziazione dell'adattatore della libreria Paging lavorando direttamente con un oggetto AsyncPagedListDiffer.

Fornisci segnaposto nella tua UI

Se vuoi che la tua UI mostri un elenco prima che l'app abbia finito di recuperare i dati, puoi mostrare agli utenti elementi segnaposto dell'elenco. PagedList gestisce questo caso presentando i dati degli articoli dell'elenco come null finché i dati non vengono caricati.

I segnaposto offrono i seguenti vantaggi:

  • Supporto per le barre di scorrimento: PagedList fornisce il numero di elementi dell'elenco a PagedListAdapter. Queste informazioni consentono all'adattatore di disegnare una barra di scorrimento che mostra le dimensioni complete dell'elenco. Man mano che vengono caricati i caricamenti pagina, la barra di scorrimento non si sposta perché l'elenco non cambia dimensione.
  • Nessun indicatore di caricamento necessario: poiché le dimensioni dell'elenco sono già note, non è necessario avvisare gli utenti che sono in fase di caricamento altri elementi. I segnaposto stessi trasmettono queste informazioni.

Prima di aggiungere il supporto per i segnaposto, tieni presente le seguenti precondizioni:

  • Richiede un set di dati numerabile: le istanze di DataSource della libreria di persistenza Room possono conteggiare i propri elementi in modo efficiente. Tuttavia, se utilizzi una soluzione di archiviazione locale personalizzata o un'architettura dei dati solo di rete, potrebbe essere costoso o addirittura impossibile determinare il numero di elementi che compongono il set di dati.
  • Richiede un adattatore per tenere conto degli elementi non caricati: l'adattatore o il meccanismo di presentazione che utilizzi per preparare l'elenco per l'inflation deve gestire gli elementi dell'elenco null. Ad esempio, quando esegui il binding dei dati a un ViewHolder, devi fornire valori predefiniti per rappresentare i dati non caricati.
  • Richiede visualizzazioni degli elementi della stessa dimensione: se le dimensioni degli elementi dell'elenco possono cambiare in base ai contenuti, ad esempio gli aggiornamenti dei social network, la dissolvenza incrociata tra gli elementi non ha un bell'aspetto. In questo caso, ti consigliamo vivamente di disattivare i segnaposto.

Invia il tuo feedback

Condividi con noi il tuo feedback e le tue idee tramite queste risorse:

Issue Tracker
Segnala i problemi per consentirci di correggere i bug.

Risorse aggiuntive

Per scoprire di più sulla libreria Paging, consulta le seguenti risorse.

Esempi

Codelab

Video