I widget delle app sono viste app in miniatura che puoi incorporare in altre app, ad esempio la 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 widget musicale di esempio:
Questo documento descrive come pubblicare un widget utilizzando un provider di widget. Per
maggiori dettagli sulla creazione di un AppWidgetHost personalizzato per ospitare
i widget dell'app, consulta Crea un host di widget.
Per informazioni su come progettare il widget, consulta la 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. - Classe
AppWidgetProvider - Definisce i metodi di base che ti consentono di interfacciarti in modo programmatico con il widget. In questo modo, ricevi trasmissioni quando il widget viene aggiornato, attivato, disattivato o eliminato. Dichiara
AppWidgetProvidernel file 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 di elaborazione complessivo 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 dei widget, ad esempio il fuso orario di un widget orologio.
- A partire da Android 12 (livello API 31), puoi fornire una configurazione predefinita e consentire agli utenti di riconfigurare il widget in un secondo momento. Per maggiori dettagli, consulta Utilizza la configurazione predefinita del widget e Consenti agli utenti di riconfigurare i widget posizionati.
- In Android 11 (livello API 30) o versioni precedenti, questa attività viene avviata ogni volta che l'utente aggiunge il widget alla schermata Home.
Consigliamo inoltre i seguenti miglioramenti: layout dei widget flessibili, miglioramenti vari, widget avanzati, widget di raccolta e creazione di un host di widget.
Dichiara l'XML AppWidgetProviderInfo
La definizione delle impostazioni dei metadati (come le dimensioni predefinite delle celle, i vincoli di ridimensionamento e le frequenze di aggiornamento) è esattamente identica sia per le visualizzazioni tradizionali che per i widget basati su Glance.
Per scoprire come definire e configurare il file XML dei metadati, consulta la sezione Dichiara l'XML AppWidgetProviderInfo di Compose-first 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 loop degli eventi del ciclo di vita sono unificati sotto la piattaforma. Nello sviluppo incentrato su Compose, queste trasmissioni vengono orchestrate 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 Utilizza la classe AppWidgetProvider per gestire le trasmissioni di Compose-first 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.
La creazione del layout del widget è semplice se hai dimestichezza con i layout. Tuttavia, tieni presente che i layout dei widget si basano 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, un View invisibile di dimensioni pari a zero che puoi utilizzare per eseguire l'inflation lazy delle 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 memorizzare lo stato e registrarsi per gli eventi di modifica dello stato.
Il seguente esempio di codice mostra come implementare questi componenti.
// 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.
Implementa gli angoli arrotondati
Il calcolo dei raggi proporzionali dello sfondo esterno e dell'interno è standard e condiviso. Nello sviluppo incentrato su Compose, questo 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 Implementa angoli arrotondati di Compose-first nella documentazione di Glance.