Creare un widget semplice

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 delle app sono visualizzazioni in miniatura delle app che puoi incorporare in altre app, ad esempio nella schermata Home, e ricevere aggiornamenti periodici. Queste visualizzazioni sono chiamate widget nell'interfaccia utente e puoi pubblicarne uno con un fornitore di widget per app (o fornitore di widget). Un componente dell'app che contiene altri widget è chiamato host di widget dell'app (o host di widget). La figura 1 mostra un widget musicale di esempio:

Esempio di widget musicale
Figura 1. Esempio di un widget musicale.

Questo documento descrive come pubblicare un widget utilizzando un fornitore di widget. Per informazioni dettagliate sulla creazione del tuo AppWidgetHost per ospitare i widget delle app, vedi Creare un host di widget.

Per informazioni su come progettare il widget, vedi Panoramica dei widget delle app.

Componenti del widget

Per creare un widget, sono necessari i seguenti componenti di base:

Oggetto AppWidgetProviderInfo
Descrive i metadati di un widget, ad esempio il layout, la frequenza di aggiornamento e la classe AppWidgetProvider. AppWidgetProviderInfo è definito in XML, come descritto in questo documento.
AppWidgetProvider corso
Definisce i metodi di base che ti consentono di interagire a livello di programmazione con il widget. Tramite questo intent, ricevi trasmissioni quando il widget viene aggiornato, attivato, disattivato o eliminato. Dichiara AppWidgetProvider nel manifest e poi implementalo, come descritto in questo documento.
Visualizza layout
Definisce il layout iniziale del widget. Il layout è definito in XML, come descritto in questo documento.

La figura 2 mostra come questi componenti si inseriscono nel flusso complessivo di elaborazione dei widget dell'app.

Flusso di elaborazione dei widget delle app
Figura 2. Flusso di elaborazione dei widget delle app.

Se il widget richiede la configurazione dell'utente, implementa l'attività di configurazione del widget dell'app. Questa attività consente agli utenti di modificare le impostazioni dei widget, ad esempio il fuso orario per un widget orologio.

Consigliamo anche i seguenti miglioramenti: layout flessibili dei widget, miglioramenti vari, widget avanzati, widget di raccolta e creazione di un host di widget.

Dichiarare il file XML AppWidgetProviderInfo

La definizione delle impostazioni dei metadati (ad esempio dimensioni predefinite delle celle, vincoli di ridimensionamento e frequenze di aggiornamento) è identica sia per le visualizzazioni tradizionali sia per i widget basati su Glance.

Per scoprire come definire e configurare il file XML dei metadati, consulta la sezione Compose-first Declare the AppWidgetProviderInfo XML section nella documentazione di Glance.

Utilizza la classe AppWidgetProvider per gestire le trasmissioni dei widget

I meccanismi del broadcast receiver della piattaforma, i filtri di dichiarazione del manifest e i cicli di eventi del ciclo di vita sono unificati nella piattaforma. Nello sviluppo basato su Compose, queste trasmissioni vengono coordinate utilizzando il wrapper GlanceAppWidgetReceiver.

Per capire come registrare il ricevitore nel manifest e implementare gli override del ciclo di vita compatibili con Hilt, consulta la sezione Utilizzare la classe AppWidgetProvider per gestire le trasmissioni nella documentazione di Glance.

Crea il layout del widget

Devi definire un layout iniziale per il widget in XML e salvarlo nella directory res/layout/ del progetto. Per maggiori dettagli, consulta le linee guida per la progettazione.

Creare il layout del widget è semplice se hai familiarità con i layout. Tuttavia, tieni presente che i layout dei widget si basano su RemoteViews, che non supporta tutti i tipi di widget di layout o visualizzazione. Non puoi utilizzare visualizzazioni personalizzate o sottoclassi delle visualizzazioni supportate da RemoteViews.

RemoteViews supporta anche ViewStub, che è un View invisibile di dimensioni zero che puoi utilizzare per gonfiare in modo differito le risorse di layout in fase di runtime.

Supporto per il comportamento stateful

Android 12 aggiunge il supporto del comportamento stateful utilizzando i seguenti componenti esistenti:

Il widget è ancora stateless. L'app deve memorizzare lo stato e registrarsi per gli eventi di modifica dello stato.

Esempio di widget della lista della spesa che mostra un comportamento stateful
Figura 3. Esempio di comportamento stateful.

Il seguente esempio di codice mostra come implementare questi componenti.

Kotlin

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

Java

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

Fornisci due layout: uno destinato ai dispositivi con Android 12 o versioni successive in res/layout-v31 e l'altro destinato alle versioni precedenti di Android 11 o precedenti nella cartella res/layout predefinita.

Implementare angoli arrotondati

Il calcolo dei raggi proporzionali interno ed esterno dello sfondo è standard e condiviso. Nello sviluppo basato su Compose, questo valore può essere impostato in modo dinamico in Kotlin insieme alle risorse del tema personalizzato.

Per implementare i raggi degli angoli o configurare stili dinamici per i dispositivi Android meno recenti, consulta la sezione Implementare gli angoli arrotondati di Compose-first nella documentazione di Glance.