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. 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 Hilfeartikel Vorschauen zur Widget Auswahl hinzufügen.

Um die Widget-Auswahl Ihrer App für Glance-Widgets zu verbessern, stellen Sie auf Geräten mit Android 15 und höher eine generierte Widget-Vorschau mit GlanceAppWidget.providePreview bereit. Geben Sie für frühere Versionen und als Fallback auf Android 15+ ein previewImage an, wenn keine generierte Vorschau verfügbar ist.

Weitere Informationen finden Sie im YouTube-Video 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 compileSdk Wert in der Datei build.gradle des Moduls auf 35 oder höher fest, damit Sie die Möglichkeit haben, RemoteViews für die Widget-Auswahl bereitzustellen

Apps können dann setWidgetPreview in GlanceAppWidgetManager verwenden. Um Missbrauch zu verhindern und Probleme mit der Systemgesundheit zu vermeiden, ist setWidgetPreview eine ratenbegrenzte API. Das Standardlimit liegt bei etwa zwei Aufrufen pro Stunde.

Aktualisierte Vorschau mit Jetpack Glance generieren

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

1. Überschreiben Sie 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 zusammensetzbare Funktion des Widget-Inhalts, damit in der Vorschau korrekte Daten angezeigt werden. Im Gegensatz zu provideGlance handelt es sich hier um 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 Ihres 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 periodische Aufgabe 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 zusammensetzbare Elemente im Vorschaubild fehlen können, relativ zur Drop-Größe des Widgets. Diese Drop-Größe wird durch die targetCellWidth und targetCellHeight definiert, falls angegeben, oder durch die minWidth und minHeight in der Infodatei des App-Widget-Anbieters.

Das liegt daran, dass Android standardmäßig nur zusammensetzbare Elemente rendert, die in der Mindestgröße des Widgets sichtbar sind. Mit anderen Worten: Android legt previewSizeMode standardmäßig auf SizeMode.Single fest. In der XML-Datei mit den Informationen zum App-Widget-Anbieter werden android:minHeight und android:minWidth verwendet, um zu bestimmen, welche zusammensetzbaren Elemente gezeichnet werden sollen.

Um dieses Problem zu beheben, überschreiben Sie previewSizeMode in Ihrem GlanceAppWidget und legen Sie es auf SizeMode.Responsive fest. Geben Sie eine Reihe von DpSize-Werten an. Dadurch werden Android alle Layoutgrößen mitgeteilt, die für das Rendern der Vorschau erforderlich sind, sodass alle Elemente korrekt angezeigt werden.

Optimieren Sie für bestimmte Formfaktoren. Geben Sie eine oder zwei Größen an, beginnend mit der Mindestgröße und entsprechend den Breakpoints Ihres Widgets. Geben Sie für die Abwärtskompatibilität mindestens ein previewImage an. Die entsprechenden Mindestwerte für DP für verschiedene Rastergrößen finden Sie in den Richtlinien für das Widget-Design.

Abwärtskompatibilität mit Widget-Vorschauen

Wenn Widget-Auswahlen auf Geräten mit älteren Versionen als Android 15 Vorschauen Ihres Widgets anzeigen sollen oder als Fallback für generierte Vorschauen auf Android 15+, geben Sie das previewImage Attribut an.

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