Utilizzo dei widget raccolta

Prova Compose

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

Jetpack Glance →

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

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

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

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

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

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

Poiché queste visualizzazioni di 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 set di dati a singoli oggetti View.

Inoltre, poiché queste visualizzazioni di raccolte 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 un RemoteViewsFactory, che è un wrapper sottile attorno all'interfaccia Adapter. Quando viene richiesto un elemento specifico della 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 di raccolta, ad esempio ListView, GridView e StackView, e i dati sottostanti per quella visualizzazione. Ecco un esempio di codice boilerplate per implementare questo servizio e questa interfaccia, tratto dall'esempio StackWidget:

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.

}
Collections.kt

Applicazione di esempio

Anche gli estratti di codice in questa sezione sono tratti dall'esempio StackWidget:

Figura 1. A StackWidget.

Questo esempio è costituito da un insieme 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 superiore nel widget per visualizzare la visualizzazione successiva o precedente. Questo è un comportamento integrato di StackView.

• Senza alcuna interazione dell'utente, il widget avanza automaticamente attraverso 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 vista stack.

• Se l'utente tocca la vista dall'alto, il widget visualizza il messaggio Toast "Vista toccata n", dove n è l'indice (posizione) della vista toccata. Per saperne di più su come implementare i comportamenti, consulta la sezione Aggiungi un comportamento ai singoli elementi.

Implementa 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 Dichiara 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, altre applicazioni non possono accedere liberamente ai dati del widget.

Ad esempio, quando crei un widget che utilizza RemoteViewsService per compilare una visualizzazione della 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 raccolte

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

<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>
widget_layout.xml

Tieni presente che le visualizzazioni vuote devono essere elementi di pari livello della visualizzazione della raccolta per cui la visualizzazione vuota rappresenta 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 i widget con raccolte

Come per i widget normali, la maggior parte del codice nella sottoclasse AppWidgetProvider in genere va in onUpdate(). La differenza principale nell'implementazione di onUpdate() quando crei un widget con le raccolte è che devi chiamare setRemoteAdapter(). In questo modo, la visualizzazione della raccolta sa dove recuperare i dati. RemoteViewsService può quindi restituire l'implementazione di RemoteViewsFactory e il widget può mostrare i dati appropriati. Quando chiami questo metodo, passa un intent che rimanda alla tua implementazione di RemoteViewsService e l'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)
}
Collections.kt

Rendere persistenti i dati

Come descritto in questa pagina, la sottoclasse RemoteViewsService fornisce RemoteViewsFactory utilizzato per compilare 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 di 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 thin attorno a Adapter.

Non puoi fare affidamento sulla persistenza di una singola istanza del tuo servizio o dei dati che contiene. Non archiviare dati nel tuo RemoteViewsService, a meno che non siano statici. Se vuoi che i dati del widget vengano conservati, l'approccio migliore è utilizzare un ContentProvider i cui dati vengono conservati 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 permanente, come un database SQL.

Nota: VedereWeatherDataProvider.java per un esempio di codice che dimostra come rendere persistenti i dati sottostanti di un widget utilizzandoContentProvider.

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

Interfaccia RemoteViewsFactory

La classe personalizzata che implementa l'interfaccia RemoteViewsFactory fornisce al widget i dati per gli elementi della sua raccolta. Per farlo, combina il file di layout XML dell'elemento del 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. RemoteViewsFactory funge da adattatore per collegare i dati alla visualizzazione della raccolta remota.

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

Il sistema chiama onCreate() quando crea la tua factory per la prima volta. Qui puoi configurare le connessioni o i 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!") }
    }

}
Collections.kt

Il metodo RemoteViewsFactory getViewAt() restituisce un oggetto RemoteViews corrispondente ai dati in corrispondenza del position specificato nel set di dati. Ecco 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)
    }
}
Collections.kt

Aggiungi un comportamento ai singoli elementi

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

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

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

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

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

• Quando l'utente tocca una visualizzazione, l'intent viene attivato 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 vengono forniti dal RemoteViewsFactory tramite RemoteViewsService.

Nota: l'esempio StackWidget utilizza una trasmissione, ma in genere un widget avvia un'attività in uno scenario come questo.

Configura il modello di pending intent

StackWidgetProvider (una sottoclasse di AppWidgetProvider) configura un pending intent. I singoli elementi di una raccolta non possono configurare i propri pending intent. Invece, la raccolta nel suo complesso configura un modello di pending intent e i singoli elementi impostano un intent di compilazione per creare un comportamento univoco elemento per elemento.

Questa classe riceve anche la trasmissione inviata quando l'utente tocca una visualizzazione. Elabora questo evento nel metodo onReceive(). Se l'azione dell'intent è TOAST_ACTION, il widget visualizza 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)
    }
}
Collections.kt

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 l'utente tocca 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)
            // ...
        }
    }
    // ...
}
Collections.kt

Mantieni 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:

Figura 2. Interazione con RemoteViewsFactory durante gli aggiornamenti.

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

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

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

Utilizza RemoteCollectionItems per trasmettere direttamente una raccolta

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

Oltre a semplificare il popolamento dell'adattatore, questo approccio rimuove anche la latenza per il popolamento di nuovi elementi quando gli utenti scorrono l'elenco per visualizzare un nuovo elemento. Questo approccio per l'impostazione dell'adattatore è preferibile se l'insieme di elementi della raccolta è relativamente piccolo. Tuttavia, ad esempio, questo approccio non funziona bene se la tua raccolta contiene numerosi Bitmaps passati 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 univoci che la raccolta può contenere. In questo modo, l'adattatore può essere riutilizzato negli 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()
)
Collections.kt

Nota: quando chiami setViewTypeCount(), passa il numero massimo di ID layout diversi utilizzati da RemoteViews in questa raccolta. In caso contrario, il conteggio dei tipi di visualizzazione viene dedotto dagli elementi forniti e l'adattatore viene ricreato quando viene inviato un aggiornamento che utilizza layout aggiuntivi.