Aggiungere le anteprime generate al selettore di widget

Le anteprime dei widget generati ti consentono di creare anteprime dinamiche e personalizzate per i tuoi widget che riflettono con precisione il modo in cui appariranno nella schermata Home di un utente. Vengono fornite tramite un'API push, il che significa che la tua 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 widget è implementato con RemoteViews, consulta Aggiungere anteprime al selettore di widget.

Per migliorare l'esperienza di selezione dei widget dell'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 fallback su Android 15 e versioni successive se un'anteprima generata non è disponibile.

Per ulteriori informazioni, vedi Arricchisci la tua app con aggiornamenti live e widget su YouTube.

Configurare l'app per le anteprime dei widget generati

Per mostrare le anteprime dei widget generati su un dispositivo Android 15 o versioni successive, imposta prima il valore compileSdk su 35 o superiore nel file del modulo build.gradle per attivare le anteprime generate nel selettore di widget.

Le app possono quindi utilizzare setWidgetPreview in GlanceAppWidgetManager. Per prevenire abusi e mitigare i problemi di integrità del sistema, setWidgetPreview è un'API con limitazione della frequenza. Il limite predefinito è di circa due chiamate all'ora.

Generare un'anteprima aggiornata con Jetpack Glance

Per i widget creati con Jetpack Glance:

1. Esegui l'override della funzione GlanceAppWidget.providePreview per fornire i contenuti componibili per l'anteprima. Come faresti in provideGlance, 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 di provideGlance, si tratta di una singola composizione senza ricomposizione o effetti.

2. Chiama GlanceAppWidgetManager.setWidgetPreviews per generare e pubblicare l'anteprima.

Non è previsto un callback dal sistema per fornire anteprime, quindi la tua 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 ha dati, ad esempio dopo l'accesso di un utente o la configurazione iniziale.
• Puoi configurare un'attività periodica per aggiornare le anteprime alla cadenza che preferisci.

Risolvere i problemi relativi alle anteprime generate

Un problema comune è che dopo aver generato un'anteprima, immagini, icone o altri composables potrebbero non essere presenti nell'immagine di anteprima rispetto alle dimensioni del widget. Le dimensioni del menu a discesa sono definite da targetCellWidth e targetCellHeight, se specificati, oppure da minWidth e minHeight nel file di informazioni sul fornitore del widget app.

Ciò si verifica perché Android, per impostazione predefinita, esegue il rendering solo dei composable 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 sul fornitore del widget dell'app per determinare quali composable 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 conosce tutte le dimensioni del layout da eseguire il rendering per l'anteprima, il che garantisce la corretta visualizzazione di tutti gli elementi.

Ottimizza per fattori di forma specifici. Fornisci una o due dimensioni a partire da quella minima e seguendo i punti di interruzione del widget. Specifica almeno un previewImage per supportare le versioni precedenti di Android. Puoi trovare i valori DP minimi appropriati per le diverse dimensioni della griglia nella guida alla progettazione dei widget.

Supportare 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.