Creare un widget semplice

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

I widget dell'app sono visualizzazioni in miniatura dell'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 una con un provider di widget dell'app (o provider 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 esempio di widget musicale:

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

Questo documento descrive come pubblicare un widget utilizzando un provider di widget. Per informazioni dettagliate sulla creazione di un AppWidgetHost personalizzato per ospitare i widget dell'app, consulta Creare un host di widget.

Per informazioni su come progettare il widget, consulta la panoramica dei widget dell'app.

Componenti del widget

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

AppWidgetProviderInfo oggetto
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 classe
Definisce i metodi di base che consentono di interagire con il widget a livello di programmazione. Tramite questa classe, ricevi le trasmissioni quando il widget viene aggiornato, attivato, disattivato o eliminato. Dichiara nel manifest AppWidgetProvidere 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 di elaborazione complessivo dei widget dell'app.

Flusso di elaborazione dei widget delle app
Figura 2. Flusso di elaborazione dei widget dell'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 del widget, ad esempio il fuso orario per un widget orologio.

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

Dichiarare l'XML AppWidgetProviderInfo

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

Per scoprire come definire e configurare il file XML dei metadati, consulta la sezione Dichiarare l'XML AppWidgetProviderInfo in stile Compose-first nella documentazione di Glance.

Utilizzare la classe AppWidgetProvider per gestire le trasmissioni dei widget

I meccanismi del broadcast receiver della piattaforma, i filtri di dichiarazione del manifest e i loop degli eventi del ciclo di vita sono unificati nella piattaforma. Nello sviluppo in stile Compose-first, queste trasmissioni vengono orchestrate utilizzando il wrapper GlanceAppWidgetReceiver.

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

Creare 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 di progettazione.

La creazione del layout del widget è semplice se hai familiarità con i layout. Tieni presente, tuttavia, che i layout dei widget sono basati su RemoteViews, che non supporta tutti i tipi di layout o widget di visualizzazione. Non puoi utilizzare visualizzazioni personalizzate o sottoclassi delle visualizzazioni supportate da RemoteViews.

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

Supporto per il comportamento stateful

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

Il widget è ancora stateless. L'app deve archiviare 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 ad Android 11 o versioni precedenti nella cartella res/layout predefinita.

Implementare gli angoli arrotondati

Il calcolo del raggio esterno dello sfondo e del raggio interno proporzionale è standard e condiviso. Nello sviluppo in stile Compose-first, questo valore può essere impostato dinamicamente 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 in stile Compose-first nella documentazione di Glance.