Generierte Vorschauen zur Widget-Auswahl hinzufügen

Mit generierten Widget-Vorschauen können Sie dynamische, personalisierte Vorschauen für Ihre Widgets erstellen, die genau zeigen, wie sie auf dem Startbildschirm eines Nutzers aussehen werden. Sie werden über eine Push-API bereitgestellt. Das bedeutet, dass Ihre App die Vorschau zu jedem Zeitpunkt 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 Hilfeartikel Vorschauen zur Widget-Auswahl hinzufügen.

Wenn du die Widget-Auswahl deiner App für Glance-Widgets verbessern möchtest, stelle eine generierte Widget-Vorschau mit GlanceAppWidget.providePreview auf Geräten mit Android 15 und höher bereit. Gib für niedrigere Versionen und als Fallback auf Android 15 und höher, wenn keine generierte Vorschau verfügbar ist, ein previewImage an.

Weitere Informationen findest du im YouTube-Video Enrich your app with live updates and widgets (Apps mit Livemeldungen und Widgets anreichern).

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, müssen Sie zuerst den Wert compileSdk in der Datei build.gradle des Moduls auf 35 oder höher festlegen, um generierte Vorschauen in der Widget-Auswahl zu aktivieren.

Apps können dann setWidgetPreview in GlanceAppWidgetManager verwenden. Um Missbrauch zu verhindern und Probleme mit dem Systemzustand zu minimieren, ist setWidgetPreview eine API mit Ratenbegrenzung. Das Standardlimit beträgt etwa zwei Aufrufe pro Stunde.

Aktualisierte Vorschau mit Jetpack Glance generieren

Gehen Sie bei Widgets, die mit Jetpack Glance erstellt wurden, so vor:

1. Überschreibe die Funktion GlanceAppWidget.providePreview, um den zusammensetzbaren Inhalt für die Vorschau bereitzustellen. Laden Sie wie in provideGlance die Daten Ihrer App und übergeben Sie sie an die Inhalts-Composable des Widgets, damit in der Vorschau die richtigen Daten angezeigt werden. Im Gegensatz zu provideGlance ist dies eine einzelne Komposition ohne Neukomposition oder Effekte.

2. Rufen Sie GlanceAppWidgetManager.setWidgetPreviews auf, 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 des Widgets ab:

• Wenn das Widget statische Informationen enthält oder eine Schnellaktion ist, legen Sie die Vorschau fest, wenn die App zum ersten Mal gestartet wird.
• Sie können die Vorschau festlegen, sobald Ihre App Daten enthält, z. B. nach der Anmeldung eines Nutzers oder der Ersteinrichtung.
• Sie können eine regelmäßige Aufgabe einrichten, um die Vorabversionen in einem bestimmten Intervall zu aktualisieren.

Fehlerbehebung bei generierten Vorschauen

Ein häufiges Problem ist, dass nach dem Erstellen einer Vorschau Bilder, Symbole oder andere Composables im Vorschaubild fehlen, je nach 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 legt standardmäßig previewSizeMode auf SizeMode.Single fest. Dabei werden android:minHeight und android:minWidth in der XML-Datei mit Informationen zum App-Widget-Anbieter verwendet, um zu bestimmen, welche Composables gezeichnet werden sollen.

Um dieses Problem zu beheben, überschreiben Sie previewSizeMode in Ihrer GlanceAppWidget und setzen Sie es auf SizeMode.Responsive. Geben Sie dabei eine Reihe von DpSize-Werten an. So erfährt Android, welche Layoutgrößen für die Vorschau gerendert werden müssen, damit alle Elemente korrekt angezeigt werden.

Für bestimmte Formfaktoren optimieren. Geben Sie eine oder zwei Größen an, beginnend mit der Mindestgröße und entsprechend den Haltepunkten Ihres Widgets. Geben Sie mindestens ein previewImage an, um ältere Android-Versionen zu unterstützen. Die entsprechenden Mindest-DP-Werte für verschiedene Rastergrößen findest du im Leitfaden zum Widget-Design.

Unterstützung älterer Android-Versionen

Wenn Sie Widget-Vorschauen auf Geräten mit Android 14 und niedriger anzeigen möchten oder wenn auf Android 15 und höher keine generierte Vorschau verfügbar ist, geben Sie das Attribut previewImage an.

Wenn Sie das Erscheinungsbild des Widgets ändern, aktualisieren Sie das Vorschaubild.