Mit generierten Widget-Vorschaubildern können Sie dynamische, personalisierte Vorschaubilder 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.
Um die Widget-Auswahl für Ihre App zu verbessern, stellen Sie auf Geräten mit Android 15 und höher eine generierte Widget-Vorschau, auf Geräten mit Android 12 bis Android 14 eine skalierte Widget-Vorschau (durch Angabe von previewLayout) und für frühere Versionen ein previewImage bereit.
Weitere Informationen finden Sie auf YouTube unter Enrich your app with live updates and widgets.
App für generierte Widget-Vorschauen einrichten
Damit generierte Widget-Vorschauen auf Geräten mit Android 15 oder höher angezeigt werden, müssen Sie zuerst den compileSdk-Wert in der Moduldatei build.gradle auf 35 oder höher festlegen, damit Sie dem Widget-Picker RemoteViews zur Verfügung stellen können.
Apps können setWidgetPreview dann entweder in GlanceAppWidgetManager oder AppWidgetManager verwenden. Um Missbrauch zu verhindern und Bedenken hinsichtlich der Systemintegrität auszuräumen, 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 hierbei um eine einzelne Komposition ohne Neukomposition oder Effekte.Rufen Sie
GlanceAppWidgetManager.setWidgetPreviewsauf, um die Vorschau zu generieren und zu veröffentlichen.
Es gibt keinen Rückruf 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. Dazu werden android:minHeight und android:minWidth im XML-Code für die Informationen zum App-Widget-Anbieter verwendet, um zu bestimmen, welche Composables gezeichnet 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 ein Bild zur Abwärtskompatibilität an. Die entsprechenden Mindest-DP-Werte für verschiedene Rastergrößen finden Sie in der Anleitung zum Widget-Design.
Aktualisierte Vorschau ohne Jetpack Glance generieren
Sie können RemoteViews ohne Glance verwenden. Im folgenden Beispiel wird eine XML-Ressource für das Widget-Layout geladen und als Vorschau festgelegt. Für die Anzeige von setWidgetPreview als Methode in diesem Snippet ist die Build-Einstellung „compileSdk“ 35 oder höher erforderlich.
AppWidgetManager.getInstance(appContext).setWidgetPreview(
ComponentName(
appContext,
ExampleAppWidgetReceiver::class.java
),
AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
RemoteViews("com.example", R.layout.widget_preview)
)
Skalierbare Widget-Vorschauen zur Widget-Auswahl hinzufügen
Ab Android 12 ist die im Widget-Picker angezeigte Widget-Vorschau skalierbar. Sie stellen es als XML-Layout bereit, das auf die Standardgröße des Widgets festgelegt ist. Bisher war die Widget-Vorschau eine statische Drawable-Ressource. In einigen Fällen wurde daher nicht genau dargestellt, wie Widgets aussehen, wenn sie dem Startbildschirm hinzugefügt werden.
Wenn Sie skalierbare Widget-Vorschauen implementieren möchten, verwenden Sie das Attribut previewLayout des Elements appwidget-provider, um stattdessen ein XML-Layout anzugeben:
<appwidget-provider
android:previewLayout="@layout/my_widget_pre>v<iew"
/appwidge>t-provider
Wir empfehlen, dass Sie dasselbe Layout wie für das tatsächliche Widget verwenden und realistische Standard- oder Testwerte angeben. Die meisten Apps verwenden dieselben previewLayout und initialLayout. Hinweise zum Erstellen genauer Vorschau-Layouts finden Sie im folgenden Abschnitt auf dieser Seite.
Wir empfehlen, sowohl das Attribut previewLayout als auch das Attribut previewImage anzugeben, damit Ihre App auf previewImage zurückgreifen kann, wenn das Gerät des Nutzers previewLayout nicht unterstützt. Das Attribut previewLayout hat Vorrang vor dem Attribut previewImage.
Abwärtskompatibilität mit Widget-Vorschauen
Wenn Sie möchten, dass in der Widget-Auswahl unter Android 11 (API‑Level 30) oder niedriger Vorschauen Ihres Widgets angezeigt werden, oder als Fallback für generierte Vorschauen, geben Sie das Attribut previewImage an.
Wenn Sie das Aussehen des Widgets ändern, aktualisieren Sie das Vorschaubild.
Genaue Vorschauen mit dynamischen Elementen erstellen
In diesem Abschnitt wird die empfohlene Vorgehensweise zum Anzeigen mehrerer Elemente in einer Widget-Vorschau für ein Widget mit einer Sammlungsansicht beschrieben. Das ist ein Widget, das ListView, GridView oder StackView verwendet. Das gilt nicht für generierte Widget-Vorschauen.
Wenn Ihr Widget eine dieser Ansichten verwendet, wird die Nutzerfreundlichkeit beeinträchtigt, wenn Sie eine skalierbare Vorschau erstellen, indem Sie das tatsächliche Widget-Layout direkt angeben und in der Widget-Vorschau keine Elemente angezeigt werden. Das liegt daran, dass die Daten für die Collection View dynamisch zur Laufzeit festgelegt werden. Das Ergebnis sieht ähnlich aus wie in Abbildung 1.
Damit Vorschauen von Widgets mit Sammlungsansichten in der Widget-Auswahl richtig angezeigt werden, empfehlen wir, eine separate Layoutdatei nur für die Vorschau zu verwenden. Diese separate Layoutdatei sollte Folgendes enthalten:
- Das tatsächliche Widget-Layout.
- Eine Platzhalter-Sammlungsansicht mit gefälschten Elementen. Sie können beispielsweise ein
ListViewsimulieren, indem Sie einen PlatzhalterLinearLayoutmit mehreren gefälschten Listenelementen angeben.
Hier ist ein Beispiel für eine ListView, das mit einer separaten Layoutdatei beginnt:
// res/layout/widget_preview.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/widget_background>"
android:orientation="vertical"
// Include the< actual widget layout that contains ListView.
include
layout="@layout/widget_view"
android:layout_width=&>quot;match_parent"
android:layout_height="wrap_content" /
// The number of fake items you include depends on the values you provide
// for min<Height or targetCellHeight in the AppWidgetProviderInfo
// definition.
TextView android:text="@string/fake_item1"
android:layout_width="match_parent"
android:l>ayout_<height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" /
TextView android:text="@string/fake_item2"
android:layout_width=&q>uo<t;match_paren>t"
android:layout_height="wrap_content"
android:layout_marginVertical="?attr/appWidgetInternalPadding" /
/LinearLayout
Geben Sie die Datei für das Vorschau-Layout an, wenn Sie das Attribut previewLayout der AppWidgetProviderInfo-Metadaten angeben. Sie geben weiterhin das tatsächliche Widget-Layout für das Attribut initialLayout an und verwenden das tatsächliche Widget-Layout, wenn Sie zur Laufzeit ein RemoteViews erstellen.
<appwidget-provider
previewLayout="@layout/widget_previe"
initialLayout="@layout>/widget_view" /
Komplexe Listenelemente
Im Beispiel im vorherigen Abschnitt werden gefälschte Listenelemente verwendet, da die Listenelemente TextView-Objekte sind. Es kann schwieriger sein, gefälschte Artikel bereitzustellen, wenn die Artikel komplexe Layouts haben.
Angenommen, ein Listenelement wird in widget_list_item.xml definiert und besteht aus zwei TextView-Objekten:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_h>eight=<"wrap_content"
TextView android:id="@id/title"
android:layout_width="match_parent"
android:layout_height="wr>ap_con<tent"
android:text="@string/fake_title" /
TextView android:id="@id/content"
android:layout_width="match_parent"
> < android:layout_height="wrap_content"
android:text="@string/fake_content" /
/LinearLayout
Wenn Sie gefälschte Listenelemente angeben möchten, können Sie das Layout mehrmals einfügen. Dadurch sind jedoch alle Listenelemente identisch. So stellen Sie eindeutige Listenelemente bereit:
Erstellen Sie eine Reihe von Attributen für die Textwerte:
<resources> <attr name="widgetTitle" format=>"<;string" / attr name="widgetC>o<ntent">;format="string" / /resourcesVerwenden Sie diese Attribute, um den Text festzulegen:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_h>eight=<"wrap_content" TextView android:id="@id/title" android:layout_width="match_parent" android:layout_height=&q>uot;wr<ap_content" android:text="?widgetTitle" / TextView android:id="@id/content" android:layout_width="match_parent&>q<uot; >android:layout_height="wrap_content" android:text="?widgetContent" / /LinearLayoutErstellen Sie so viele Stile wie für die Vorschau erforderlich. Definieren Sie die Werte in jedem Stil neu:
<resources> <style name="Theme.Widget.List>Item"<; item name=&qu><ot;wi>dgetTitle<"/item item ><name=>"<;widge>tCont<ent"/item /style style name=&q>uot;Theme<.Widget.ListItem.Previe>w1" < >item name<="widgetTitle"F>ake Title 1/it<em > < item >name=<"widgetContent"Fake content 1/ite>m /st<yle style name=&quo>t;Theme.Widg<et.Li>stItem.Pr<eview2" item> name="wi<dgetT>itle&<quot;F>ak<e title 2/>item item name="widgetContent"Fake content 2/item /style /resourcesWenden Sie die Stile auf die Platzhalterelemente im Vorschaulayout an:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_heigh>t=&quo<t;wrap_content" ... include layo>ut=&qu<ot;@layout/widget_view" ... / include layout="@layout/widget_list_item" andro>id:the<me="@style/Theme.Widget.ListItem.Preview1" / include layout="@layout/widget_list_item>&q<uot; >android:theme="@style/Theme.Widget.ListItem.Preview2" / /LinearLayout