Utilizzo dei widget raccolta

Prova Compose
Jetpack Compose è il toolkit UI consigliato per Android. Scopri come creare widget utilizzando API in stile Compose.
Jetpack Glance →

I widget raccolta sono specializzati nella visualizzazione di molti elementi dello stesso tipo, ad esempio raccolte di immagini da un'app di galleria, articoli da un'app di notizie o messaggi da un'app di comunicazione. I widget raccolta in genere si concentrano su due casi d'uso: la navigazione nella raccolta e l'apertura di un elemento della raccolta nella visualizzazione dettagliata. I widget delle raccolte possono scorrere verticalmente.

Questi widget utilizzano RemoteViewsService per visualizzare raccolte supportate da dati remoti, ad esempio di un fornitore di contenuti. Il widget presenta i dati utilizzando uno dei seguenti tipi di visualizzazione, noti come visualizzazioni raccolta:

ListView: una visualizzazione che mostra gli elementi in un elenco a scorrimento verticale.

GridView: una visualizzazione che mostra gli elementi in una griglia a scorrimento bidimensionale.

StackView: una visualizzazione a schede impilate, simile a un rolodex, in cui l'utente può scorrere la scheda anteriore verso l'alto o verso il basso per visualizzare la scheda precedente o successiva, rispettivamente.

AdapterViewFlipper: un ViewAnimator supportato da un adattatore che anima due o più visualizzazioni. Viene mostrato un solo bambino alla volta.

Poiché queste visualizzazioni della raccolta mostrano raccolte supportate da dati remoti, utilizzano un Adapter per associare la propria interfaccia utente ai dati. Un Adapter associa singoli elementi di un insieme di dati a singoli oggetti View.

Poiché queste visualizzazioni della raccolta sono supportate da adattatori, il framework Android deve includere un'architettura aggiuntiva per supportarne l'utilizzo nei widget. Nel contesto di un widget, Adapter viene sostituito da RemoteViewsFactory, che è un wrapper sottile intorno all'interfaccia Adapter. Quando viene richiesto un elemento specifico nella raccolta, RemoteViewsFactory crea e restituisce l'elemento per la raccolta come oggetto RemoteViews. Per includere una visualizzazione raccolta nel widget, implementa RemoteViewsService e RemoteViewsFactory.

RemoteViewsService è un servizio che consente a un adattatore remoto di richiedere oggetti RemoteViews. RemoteViewsFactory è un'interfaccia per un adattatore tra una visualizzazione raccolta, ad esempio ListView, GridView e StackView, e i dati sottostanti per quella visualizzazione. Dall'StackWidget esempio, ecco un esempio di codice boilerplate per implementare questo servizio e questa interfaccia:

class StackWidgetService : RemoteViewsService() {
    override fun onGetViewFactory(intent: Intent): RemoteViewsFactory =
        StackRemoteViewsFactory(this.applicationContext, intent)
}

class StackRemoteViewsFactory(
    private val context: Context, intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

    // See the RemoteViewsFactory API reference for the full list of methods to implement.

}

Applicazione di esempio

Gli estratti di codice in questa sezione sono tratti anche dall'StackWidget esempio:

Un widget StackWidget che mostra le visualizzazioni impilate
Figura 1. Un StackWidget.

Questo campione è costituito da una pila di dieci visualizzazioni che mostrano i valori da zero a nove. Il widget di esempio ha i seguenti comportamenti principali:

  • L'utente può scorrere verticalmente la visualizzazione in alto nel widget per visualizzare la visualizzazione successiva o precedente. Questo è un comportamento integrato di StackView.

  • Senza alcuna interazione dell'utente, il widget scorre automaticamente le sue visualizzazioni in sequenza, come una presentazione. Ciò è dovuto all'impostazione android:autoAdvanceViewId="@id/stack_view" nel file res/xml/stackwidgetinfo.xml. Questa impostazione si applica all'ID vista, che in questo caso è l'ID vista della visualizzazione a schede.

  • Se l'utente tocca la visualizzazione in alto, il widget mostra il messaggio Toast "Visualizzazione toccata n", dove n è l'indice (posizione) della visualizzazione toccata. Per ulteriori informazioni su come implementare i comportamenti, consulta la sezione Aggiungere un comportamento a singoli elementi.

Implementare i widget con le raccolte

Per implementare un widget con raccolte, segui la procedura per implementare qualsiasi widget, seguita da alcuni passaggi aggiuntivi: modifica il manifest, aggiungi una visualizzazione raccolta al layout del widget e modifica la sottoclasse AppWidgetProvider.

Manifest per i widget con raccolte

Oltre ai requisiti elencati in Dichiarare un widget nel manifest, devi consentire ai widget con raccolte di eseguire il binding al tuo RemoteViewsService. Per farlo, dichiara il servizio nel file manifest con l'autorizzazione BIND_REMOTEVIEWS. In questo modo, si impedisce ad altre applicazioni di accedere liberamente ai dati del widget.

Ad esempio, quando crei un widget che utilizza RemoteViewsService per popolare una visualizzazione raccolta, la voce del manifest potrebbe avere il seguente aspetto:

<service android:name="MyWidgetService"
    android:permission="android.permission.BIND_REMOTEVIEWS" />

In questo esempio, android:name="MyWidgetService" si riferisce alla sottoclasse di RemoteViewsService.

Layout per i widget con le raccolte

Il requisito principale per il file XML di layout del widget è che includa una delle viste raccolta: ListView, GridView, StackView o AdapterViewFlipper. Ecco il file widget_layout.xml per l'StackWidget esempio:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <StackView
        android:id="@+id/stack_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:loopViews="true" />
    <TextView
        android:id="@+id/empty_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:background="@drawable/widget_item_background"
        android:textColor="#ffffff"
        android:textStyle="bold"
        android:text="@string/empty_view_text"
        android:textSize="20sp" />
</FrameLayout>

Tieni presente che le visualizzazioni vuote devono essere elementi di pari livello della visualizzazione della raccolta per cui rappresentano lo stato vuoto.

Oltre al file di layout per l'intero widget, crea un altro file di layout che definisca il layout per ogni elemento della raccolta, ad esempio un layout per ogni libro di una raccolta di libri. L'esempio StackWidget ha un solo file di layout degli elementi, widget_item.xml, poiché tutti gli elementi utilizzano lo stesso layout.

Classe AppWidgetProvider per widget con raccolte

Come per i widget normali, la maggior parte del codice nella sottoclasse AppWidgetProvider in genere si trova in onUpdate(). La principale differenza nell'implementazione per onUpdate() durante la creazione di un widget con raccolte è che devi chiamare setRemoteAdapter(). Indica alla visualizzazione della raccolta da dove recuperare i dati. RemoteViewsService può quindi restituire l'implementazione di RemoteViewsFactory e il widget può fornire i dati appropriati. Quando chiami questo metodo, passa un intent che punta alla tua implementazione di RemoteViewsService e all'ID widget che specifica il widget da aggiornare.

Ad esempio, ecco come l'esempio StackWidget implementa il metodo di callback onUpdate() per impostare RemoteViewsService come adattatore remoto per la raccolta di widget:

override fun onUpdate(
    context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray
) {
    // Update each of the widgets with the remote adapter.
    appWidgetIds.forEach { appWidgetId ->

        // Set up the intent that starts the StackViewService, which
        // provides the views for this collection.
        val intent = Intent(context, StackWidgetService::class.java).apply {
            // Add the widget ID to the intent extras.
            putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
            data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
        }
        // Instantiate the RemoteViews object for the widget layout.
        val views = RemoteViews(context.packageName, R.layout.widget_layout).apply {
            // Set up the RemoteViews object to use a RemoteViews adapter.
            // This adapter connects to a RemoteViewsService through the
            // specified intent.
            // This is how you populate the data.
            setRemoteAdapter(R.id.stack_view, intent)

            // The empty view is displayed when the collection has no items.
            // It must be in the same layout used to instantiate the
            // RemoteViews object.
            setEmptyView(R.id.stack_view, R.id.empty_view)
        }

        // Do additional processing specific to this widget.

        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds)
}

Conservare i dati

Come descritto in questa pagina, la sottoclasse RemoteViewsService fornisce l'RemoteViewsFactory utilizzato per popolare la visualizzazione della raccolta remota.

In particolare, segui questi passaggi:

  1. Sottoclasse RemoteViewsService. RemoteViewsService è il servizio tramite il quale un adattatore remoto può richiedere RemoteViews.

  2. Nella sottoclasse RemoteViewsService, includi una classe che implementa l'interfaccia RemoteViewsFactory. RemoteViewsFactory è un'interfaccia per un adattatore tra una visualizzazione raccolta remota, ad esempio ListView, GridView, StackView e i dati sottostanti per quella visualizzazione. La tua implementazione è responsabile della creazione di un oggetto RemoteViews per ogni elemento del set di dati. Questa interfaccia è un wrapper sottile intorno a Adapter.

Non puoi fare affidamento su una singola istanza del tuo servizio o su qualsiasi dato contenga per la persistenza. Non archiviare dati in RemoteViewsService a meno che non siano statici. Se vuoi che i dati del widget vengano mantenuti, l'approccio migliore è utilizzare un ContentProvider i cui dati vengono mantenuti oltre il ciclo di vita del processo. Ad esempio, un widget di un negozio di alimentari può memorizzare lo stato di ogni articolo della lista della spesa in una posizione persistente, ad esempio un database SQL.

I contenuti principali dell'implementazione di RemoteViewsService sono i relativi RemoteViewsFactory, descritti nella sezione seguente.

Interfaccia RemoteViewsFactory

La classe personalizzata che implementa l'interfaccia RemoteViewsFactory fornisce al widget i dati per gli elementi della raccolta. A questo scopo, combina il file di layout XML dell'elemento widget con un'origine dati. Questa origine dati può essere qualsiasi cosa, da un database a un array. Nell'esempio StackWidget, l'origine dati è un array di WidgetItems. La funzione RemoteViewsFactory funge da adattatore per collegare i dati alla visualizzazione della raccolta remota.

I due metodi più importanti da implementare per la sottoclasse RemoteViewsFactory sono onCreate() e getViewAt().

Il sistema chiama onCreate() quando crei la tua fabbrica per la prima volta. Qui puoi configurare connessioni o cursori all'origine dati. Ad esempio, l'esempio StackWidget utilizza onCreate() per inizializzare un array di oggetti WidgetItem. Quando il widget è attivo, il sistema accede a questi oggetti utilizzando la loro posizione di indice nell'array e visualizza il testo che contengono.

Ecco un estratto dell'implementazione di RemoteViewsFactory dell'esempio StackWidget che mostra parti del metodo onCreate():

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
    private val context: Context
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating content,
        // must be deferred to onDataSetChanged() or getViewAt(). Taking
        // more than 20 seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
    }

}

Il metodo RemoteViewsFactory getViewAt() restituisce un oggetto RemoteViews corrispondente ai dati in corrispondenza del position specificato nel set di dati. Di seguito è riportato un estratto dell'implementazione di RemoteViewsFactory dell'esempio StackWidget:

override fun getViewAt(position: Int): RemoteViews {
    // Construct a remote views item based on the widget item XML file
    // and set the text based on the position.
    return RemoteViews(context.packageName, R.layout.widget_item).apply {
        setTextViewText(R.id.widget_item, widgetItems[position].text)
    }
}

Aggiungere un comportamento a singoli elementi

Le sezioni precedenti mostrano come associare i dati alla raccolta di widget. Ma se vuoi aggiungere un comportamento dinamico ai singoli elementi nella visualizzazione raccolta?

Come descritto in Gestire gli eventi con la classe onUpdate(), in genere utilizzi setOnClickPendingIntent() per impostare il comportamento di clic di un oggetto, ad esempio per fare in modo che un pulsante avvii un Activity. Tuttavia, questo approccio non è consentito per le visualizzazioni secondarie in un singolo elemento della raccolta. Ad esempio, puoi utilizzare setOnClickPendingIntent() per configurare un pulsante globale nel widget Gmail che avvia l'app, ma non nei singoli elementi dell'elenco.

Per aggiungere il comportamento di clic ai singoli elementi di una raccolta, utilizza setOnClickFillInIntent(). Configura un modello di pending intent per la visualizzazione della raccolta e imposta un intent di compilazione su ogni elemento della raccolta utilizzando il tuo RemoteViewsFactory.

Questa sezione utilizza l'esempio StackWidget per descrivere come aggiungere un comportamento ai singoli elementi. Nell'esempio StackWidget, se l'utente tocca la visualizzazione in alto, il widget mostra il messaggio Toast "Visualizzazione toccata n", dove n è l'indice (posizione) della visualizzazione toccata. Ecco come funziona:

  • La classe StackWidgetProvider, una sottoclasse di AppWidgetProvider, crea un pending intent con un'azione personalizzata chiamata TOAST_ACTION.

  • Quando l'utente tocca una visualizzazione, l'intent si attiva e trasmette TOAST_ACTION.

  • Questa trasmissione viene intercettata dal metodo onReceive() della classe StackWidgetProvider e il widget mostra il messaggio Toast per la visualizzazione toccata. I dati per gli elementi della raccolta sono forniti da RemoteViewsFactory tramite RemoteViewsService.

Configurare il modello di intent in sospeso

StackWidgetProvider (una sottoclasse di AppWidgetProvider) configura un pending intent. I singoli elementi di una raccolta non possono configurare i propri intent in attesa. Al contrario, la raccolta nel suo complesso configura un modello di intent in attesa e i singoli elementi impostano un intent di riempimento per creare un comportamento unico per ogni elemento.

Questa classe riceve anche la trasmissione inviata quando l'utente tocca una visualizzazione. Elabora questo evento nel suo metodo onReceive(). Se l'azione dell'intent è TOAST_ACTION, il widget mostra un messaggio Toast per la visualizzazione corrente.

const val TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION"
const val EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM"

class StackWidgetProvider : AppWidgetProvider() {

    // ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks whether the intent's action is TOAST_ACTION. If it is, the
    // widget displays a Toast message for the current item.
    override fun onReceive(context: Context, intent: Intent) {
        val mgr: AppWidgetManager = AppWidgetManager.getInstance(context)
        if (intent.action == TOAST_ACTION) {
            val appWidgetId: Int = intent.getIntExtra(
                AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID
            )
            // EXTRA_ITEM represents a custom value provided by the Intent
            // passed to the setOnClickFillInIntent() method to indicate the
            // position of the clicked item. See StackRemoteViewsFactory in
            // Set the fill-in Intent for details.
            val viewIndex: Int = intent.getIntExtra(EXTRA_ITEM, 0)
            Toast.makeText(context, "Touched view $viewIndex", Toast.LENGTH_SHORT).show()
        }
        super.onReceive(context, intent)
    }

    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
    ) {
        // Update each of the widgets with the remote adapter.
        appWidgetIds.forEach { appWidgetId ->

            // Sets up the intent that points to the StackViewService that
            // provides the views for this collection.
            val intent = Intent(context, StackWidgetService::class.java).apply {
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                // When intents are compared, the extras are ignored, so embed
                // the extra sinto the data so that the extras are not ignored.
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
            }
            val rv = RemoteViews(context.packageName, R.layout.widget_layout).apply {
                setRemoteAdapter(R.id.stack_view, intent)

                // The empty view is displayed when the collection has no items.
                // It must be a sibling of the collection view.
                setEmptyView(R.id.stack_view, R.id.empty_view)
            }

            // This section makes it possible for items to have individualized
            // behavior. It does this by setting up a pending intent template.
            // Individuals items of a collection can't set up their own pending
            // intents. Instead, the collection as a whole sets up a pending
            // intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            val toastPendingIntent: PendingIntent = Intent(
                context,
                StackWidgetProvider::class.java
            ).run {
                // Set the action for the intent.
                // When the user touches a particular view, it has the effect of
                // broadcasting TOAST_ACTION.
                action = TOAST_ACTION
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))

                // The template must be mutable, because each item fills in its
                // own extras through setOnClickFillInIntent().
                PendingIntent.getBroadcast(
                    context, 0, this,
                    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE
                )
            }
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent)

            appWidgetManager.updateAppWidget(appWidgetId, rv)
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds)
    }
}

Imposta l'intent di compilazione

Il tuo RemoteViewsFactory deve impostare un intent di compilazione su ogni elemento della raccolta. In questo modo è possibile distinguere la singola azione al clic di un determinato elemento. L'intent di compilazione viene quindi combinato con il modello PendingIntent per determinare l'intent finale che viene eseguito quando viene toccato l'elemento.

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
    private val context: Context,
    intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>
    private val appWidgetId: Int = intent.getIntExtra(
        AppWidgetManager.EXTRA_APPWIDGET_ID,
        AppWidgetManager.INVALID_APPWIDGET_ID
    )

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data source.
        // Heavy lifting, such as downloading or creating content, must be
        // deferred to onDataSetChanged() or getViewAt(). Taking more than 20
        // seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
        // ...
    }

    // ...

    override fun getViewAt(position: Int): RemoteViews {
        // Construct a remote views item based on the widget item XML file
        // and set the text based on the position.
        return RemoteViews(context.packageName, R.layout.widget_item).apply {
            setTextViewText(R.id.widget_item, widgetItems[position].text)

            // Set a fill-intent to fill in the pending intent template.
            // that is set on the collection view in StackWidgetProvider.
            val fillInIntent = Intent().apply {
                Bundle().also { extras ->
                    extras.putInt(EXTRA_ITEM, position)
                    putExtras(extras)
                }
            }
            // Make it possible to distinguish the individual on-click
            // action of a given item.
            setOnClickFillInIntent(R.id.widget_item, fillInIntent)
            // ...
        }
    }
    // ...
}

Mantenere aggiornati i dati della raccolta

La figura 2 illustra il flusso di aggiornamento in un widget che utilizza le raccolte. Mostra come il codice del widget interagisce con RemoteViewsFactory e come puoi attivare gli aggiornamenti:

Interazione con RemoteViewsFactory durante gli aggiornamenti
Figura 2. Interazione con RemoteViewsFactory durante gli aggiornamenti.

I widget che utilizzano le raccolte possono fornire agli utenti contenuti aggiornati. Ad esempio, il widget Gmail offre agli utenti un'istantanea della loro posta in arrivo. Per renderlo possibile, attiva la visualizzazione RemoteViewsFactory e della raccolta per recuperare e visualizzare i nuovi dati.

Per farlo, utilizza AppWidgetManager per chiamare notifyAppWidgetViewDataChanged(). Questa chiamata comporta un callback al metodo onDataSetChanged() dell'oggetto RemoteViewsFactory, che ti consente di recuperare nuovi dati.

Puoi eseguire operazioni che richiedono un'elaborazione intensa in modo sincrono all'interno del callback onDataSetChanged(). Questa chiamata viene completata prima che i metadati o i dati delle visualizzazioni vengano recuperati da RemoteViewsFactory. Puoi anche eseguire operazioni che richiedono un'elaborazione intensiva all'interno del metodo getViewAt(). Se questa chiamata richiede molto tempo, la visualizzazione di caricamento, specificata dal metodo getLoadingView() dell'oggetto RemoteViewsFactory, viene visualizzata nella posizione corrispondente della visualizzazione raccolta finché non viene restituita.

Utilizza RemoteCollectionItems per passare direttamente una raccolta

Android 12 (livello API 31) aggiunge il metodo setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items), che consente alla tua app di passare una raccolta direttamente durante il popolamento di una visualizzazione raccolta. Se imposti l'adattatore utilizzando questo metodo, non devi implementare un RemoteViewsFactory e non devi chiamare notifyAppWidgetViewDataChanged().

Oltre a semplificare il completamento dell'adattatore, questo approccio elimina anche la latenza per il completamento di nuovi elementi quando gli utenti scorrono l'elenco per visualizzare un nuovo elemento. Questo approccio all'impostazione dell'adattatore è preferibile finché il set di elementi della raccolta è relativamente piccolo. Tuttavia, ad esempio, questo approccio non funziona bene se la raccolta contiene numerosi Bitmaps da trasferire a setImageViewBitmap.

Se la raccolta non utilizza un insieme costante di layout, ovvero se alcuni elementi sono presenti solo a volte, utilizza setViewTypeCount per specificare il numero massimo di layout unici che la raccolta può contenere. In questo modo, l'adattatore può essere riutilizzato in tutti gli aggiornamenti del widget dell'app.

Ecco un esempio di come implementare le raccolte RemoteViews semplificate.

val itemLayouts = listOf(
    R.layout.item_type_1,
    R.layout.item_type_2,
    // ...
)

remoteView.setRemoteAdapter(
    R.id.list_view,
    RemoteViews.RemoteCollectionItems.Builder()
        .addItem(/* id= */ ID_1, RemoteViews(context.packageName, R.layout.item_type_1))
        .addItem(/* id= */ ID_2, RemoteViews(context.packageName, R.layout.item_type_2))
        // ...
        .setViewTypeCount(itemLayouts.count())
        .build()
)