Le anteprime dei widget generate ti consentono di creare anteprime dinamiche e personalizzate per i tuoi widget che riflettono con precisione l'aspetto che avranno nella schermata Home di un utente. Vengono fornite tramite un'API push, il che significa che l'app fornisce l'anteprima in qualsiasi momento del suo ciclo di vita senza ricevere una richiesta esplicita dall'host del widget.
Questa guida spiega come fornire anteprime per i widget basati su Glance. Se il tuo widget è implementato con RemoteViews, consulta Aggiungi anteprime al selettore di widget.
Per migliorare l'esperienza del selettore di widget della tua app per i widget Glance, fornisci un'anteprima del widget generata utilizzando GlanceAppWidget.providePreview sui dispositivi Android 15 e versioni successive e specifica un previewImage per le versioni precedenti e come riserva su Android 15 e versioni successive se non è disponibile un'anteprima generata.
Per saperne di più, guarda il video Arricchisci la tua app con aggiornamenti in tempo reale e widget su YouTube.
Configura l'app per le anteprime dei widget generate
Per mostrare le anteprime dei widget generate su un dispositivo Android 15 o versioni successive, imposta innanzitutto il valore compileSdk su 35 o un valore superiore nel file build.gradle del modulo per attivare le anteprime generate nel selettore di widget.
Le app possono quindi utilizzare setWidgetPreview in GlanceAppWidgetManager. Per prevenire
comportamenti illeciti e mitigare i problemi di integrità del sistema, setWidgetPreview è un'API
con limitazione di frequenza. Il limite predefinito è di circa due chiamate all'ora.
Genera un'anteprima aggiornata con Jetpack Glance
Per i widget creati con Jetpack Glance, segui questi passaggi:
Esegui l'override della funzione
GlanceAppWidget.providePreviewper fornire i contenuti componibili per l'anteprima. Come faresti inprovideGlance, carica i dati della tua app e passali al composable dei contenuti del widget per fare in modo che l'anteprima mostri dati accurati. A differenza diprovideGlance, si tratta di una singola composizione senza ricomposizione o effetti.Chiama
GlanceAppWidgetManager.setWidgetPreviewsper generare e pubblicare l'anteprima.
Non esiste un callback dal sistema per fornire le anteprime, quindi l'app deve decidere quando chiamare setWidgetPreviews. La strategia di aggiornamento dipende dal caso d'uso del widget:
- Se il widget contiene informazioni statiche o è un'azione rapida, imposta l'anteprima al primo avvio dell'app.
- Puoi impostare l'anteprima una volta che l'app contiene dati, ad esempio dopo l'accesso di un utente o la configurazione iniziale.
- Puoi configurare un'attività periodica per aggiornare le anteprime con una cadenza scelta.
Risolvi i problemi relativi alle anteprime generate
Un problema comune è che, dopo aver generato un'anteprima, immagini, icone o altri elementi componibili potrebbero non essere presenti nell'immagine di anteprima, in base alle dimensioni di rilascio del widget. Questa dimensione di rilascio è definita da targetCellWidth e targetCellHeight, se specificati, o da minWidth e minHeight nel file di informazioni del provider di widget dell'app.
Questo accade perché Android, per impostazione predefinita, esegue il rendering solo dei composabili visibili alle dimensioni minime del widget. In altre parole, Android imposta previewSizeMode su
SizeMode.Single per impostazione predefinita. Utilizza android:minHeight e android:minWidth
nel file XML delle informazioni del provider di widget dell'app per determinare quali composabili disegnare.
Per risolvere il problema, esegui l'override di previewSizeMode in GlanceAppWidget e impostalo su
SizeMode.Responsive, fornendo un insieme di valori DpSize. In questo modo, Android riceve tutte le dimensioni del layout di cui ha bisogno per eseguire il rendering dell'anteprima, garantendo la corretta visualizzazione di tutti gli elementi.
Ottimizza per fattori di forma specifici. Fornisci una o due dimensioni a partire dal minimo e seguendo i breakpoint del widget. Specifica almeno un
previewImage per supportare le versioni di Android precedenti. Puoi trovare i
valori minimi di dp appropriati per le diverse dimensioni della griglia nelle
indicazioni per la progettazione dei widget.
Supporta versioni di Android precedenti
Per mostrare le anteprime dei widget sui dispositivi con Android 14 e versioni precedenti o quando un'anteprima generata non è disponibile su Android 15 e versioni successive, specifica l'attributo previewImage.
Se modifichi l'aspetto del widget, aggiorna l'immagine di anteprima.