Mit generierten Widget-Vorschauen können Sie dynamische, personalisierte Vorschauen für Ihre Widgets erstellen, die genau widerspiegeln, wie sie auf dem Startbildschirm eines Nutzers angezeigt werden. Sie werden über eine Push-API bereitgestellt. Das bedeutet, dass Ihre App die Vorschau zu jedem Zeitpunkt während ihres Lebenszyklus bereitstellt, ohne eine explizite Anfrage vom Widget-Host zu erhalten.
In diesem Leitfaden wird beschrieben, wie Sie Vorschauen für Glance-basierte Widgets bereitstellen. Wenn Ihr Widget mit RemoteViews implementiert ist, lesen Sie den Abschnitt Vorschauen zur Widget-Auswahl hinzufügen.
Um die Auswahl von Glance-Widgets in Ihrer App zu verbessern, sollten Sie für Geräte mit Android 15 und höher eine generierte Widget-Vorschau mit GlanceAppWidget.providePreview bereitstellen und für niedrigere Versionen sowie als Fallback unter Android 15+ eine previewImage angeben, wenn keine generierte Vorschau verfügbar ist.
Weitere Informationen finden Sie auf YouTube unter Enrich your app with live updates and widgets.
App für generierte Widget-Vorschauen einrichten
Wenn Sie generierte Widget-Vorschauen auf einem Gerät mit Android 15 oder höher anzeigen möchten, legen Sie zuerst den Wert compileSdk in der Moduldatei build.gradle auf 35 oder höher fest, um generierte Vorschauen in der Widget-Auswahl zu aktivieren.
Apps können dann setWidgetPreview in GlanceAppWidgetManager verwenden. Um Missbrauch zu verhindern und Bedenken hinsichtlich der Systemintegrität zu minimieren, ist setWidgetPreview eine API mit Ratenbegrenzung. Das Standardlimit liegt bei etwa zwei Anrufen pro Stunde.
Aktualisierte Vorschau mit Jetpack Glance generieren
Gehen Sie für mit Jetpack Glance erstellte Widgets so vor:
Überschreiben Sie die Funktion
GlanceAppWidget.providePreview, um den zusammensetzbaren Inhalt für die Vorschau bereitzustellen. Laden Sie wie inprovideGlancedie Daten Ihrer App und übergeben Sie sie an die Content-Composable-Funktion des Widgets, damit in der Vorschau korrekte Daten angezeigt werden. Im Gegensatz zuprovideGlancehandelt es sich um eine einzelne Komposition ohne Neukomposition oder Effekte.Rufen Sie
GlanceAppWidgetManager.setWidgetPreviewsauf, um die Vorschau zu generieren und zu veröffentlichen.
Es gibt keinen Callback vom System, um Vorschauen bereitzustellen. Ihre App muss also entscheiden, wann setWidgetPreviews aufgerufen werden soll. Die Aktualisierungsstrategie hängt vom Anwendungsfall Ihres Widgets ab:
- Wenn das Widget statische Informationen enthält oder eine Schnellaktion ist, legen Sie die Vorschau beim ersten Starten der App fest.
- Sie können die Vorschau festlegen, sobald Ihre App Daten hat, z. B. nach der Anmeldung eines Nutzers oder der Ersteinrichtung.
- Sie können einen regelmäßigen Task einrichten, um die Vorschauen in einem bestimmten Rhythmus zu aktualisieren.
Fehlerbehebung bei generierten Vorschauen
Ein häufiges Problem ist, dass nach dem Generieren einer Vorschau Bilder, Symbole oder andere Composables im Vorschaubild fehlen, bezogen auf die Drop-Größe des Widgets. Diese Drop-Größe wird durch targetCellWidth und targetCellHeight (falls angegeben) oder durch minWidth und minHeight in der Datei mit Informationen zum App-Widget-Anbieter definiert.
Das liegt daran, dass Android standardmäßig nur Composables rendert, die bei der Mindestgröße des Widgets sichtbar sind. Mit anderen Worten: Android setzt previewSizeMode standardmäßig auf SizeMode.Single. Dabei werden android:minHeight und android:minWidth im XML-Code für die Informationen zum App-Widget-Anbieter verwendet, um zu bestimmen, welche Composables gerendert werden sollen.
Um das Problem zu beheben, überschreiben Sie previewSizeMode in Ihrem GlanceAppWidget und legen Sie es auf SizeMode.Responsive fest. Geben Sie dazu eine Reihe von DpSize-Werten an. So wird Android mitgeteilt, welche Layoutgrößen für die Vorschau gerendert werden müssen, damit alle Elemente richtig angezeigt werden.
Für bestimmte Formfaktoren optimieren Geben Sie ein oder zwei Größen an, die mit der Mindestgröße beginnen und den Breakpoints Ihres Widgets entsprechen. Geben Sie mindestens eine previewImage zur Unterstützung niedrigerer Android-Versionen an. Die entsprechenden Mindest-DP-Werte für verschiedene Rastergrößen finden Sie in den Richtlinien für das Widget-Design.
Unterstützung niedrigerer Android-Versionen
Wenn Sie Widget-Vorschaubilder auf Geräten mit Android 14 und niedriger anzeigen möchten oder wenn auf Geräten mit Android 15 und höher kein generiertes Vorschaubild verfügbar ist, geben Sie das Attribut previewImage an.
Wenn Sie das Aussehen des Widgets ändern, aktualisieren Sie das Vorschaubild.