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 tuo 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+ se un'anteprima generata non è disponibile.

Per saperne di più, guarda il video 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 di compileSdk su 35 o versioni successive nel file del modulo build.gradle per avere la possibilità di fornire RemoteViews al 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 componenti 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 del 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 provider 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 che tutti gli elementi vengano visualizzati correttamente.

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 la compatibilità con le versioni precedenti. Puoi trovare i valori DP minimi appropriati per le diverse dimensioni della griglia nella guida alla progettazione dei widget.

Nota :preferisci SizeMode.Exact a SizeMode.Responsive quando ridimensioni il widget (non l'anteprima). Consulta la documentazione per una panoramica di SizeMode.

Compatibilità con le versioni precedenti con le anteprime dei widget

Per consentire ai selettori di widget sui dispositivi con versioni precedenti ad Android 15 di mostrare le anteprime del widget o come fallback per le anteprime generate su Android 15 e versioni successive, specifica l'attributo previewImage.

Se modifichi l'aspetto del widget, aggiorna l'immagine di anteprima.