Generierte Vorschauen zur Widget-Auswahl hinzufügen

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 einem beliebigen Zeitpunkt während ihres Lebenszyklus bereitstellt, ohne eine explizite Anfrage vom Widget-Host zu erhalten.

Um die Auswahl von Widgets in Ihrer App zu verbessern, sollten 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 bereitstellen.

Weitere Informationen finden Sie auf YouTube im Video 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 bei Widgets, die mit Jetpack Glance erstellt wurden, so vor:

1. Überschreiben Sie die GlanceAppWidget.providePreview-Funktion, um den zusammensetzbaren Inhalt für die Vorschau bereitzustellen. Laden Sie wie in provideGlance die Daten Ihrer App und übergeben Sie sie an die Content-Composable-Funktion des Widgets, damit in der Vorschau korrekte Daten angezeigt werden. Im Gegensatz zu provideGlance ist dies eine einzelne Komposition ohne Re-Komposition 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 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-Provider verwendet, um zu bestimmen, welche Composables gezeichnet werden sollen.

Um dieses 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)
)
AppWidgetSnippets.kt

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_preview">
</appwidget-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 ein 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 der 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 ListView simulieren, indem Sie einen Platzhalter LinearLayout mit 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="match_parent"
        android:layout_height="wrap_content" />

    // The number of fake items you include depends on the values you provide
    // for minHeight or targetCellHeight in the AppWidgetProviderInfo
    // definition.

    <TextView android:text="@string/fake_item1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

    <TextView android:text="@string/fake_item2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

</LinearLayout>

Geben Sie die Vorschau-Layoutdatei 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_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        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:

1. Erstellen Sie eine Reihe von Attributen für die Textwerte:

   <resources>
       <attr name="widgetTitle" format="string" />
       <attr name="widgetContent" format="string" />
   </resources>
   

2. Verwenden Sie diese Attribute, um den Text festzulegen:

   <LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
           android:layout_width="match_parent"
           android:layout_height="wrap_content">
   
       <TextView android:id="@id/title"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetTitle" />
   
       <TextView android:id="@id/content"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetContent" />
   </LinearLayout>
   

3. Erstellen Sie so viele Stile, wie für die Vorschau erforderlich sind. Definieren Sie die Werte in jedem Stil neu:

   <resources>
   
       <style name="Theme.Widget.ListItem">
           <item name="widgetTitle"></item>
           <item name="widgetContent"></item>
       </style>
       <style name="Theme.Widget.ListItem.Preview1">
           <item name="widgetTitle">Fake Title 1</item>
           <item name="widgetContent">Fake content 1</item>
       </style>
       <style name="Theme.Widget.ListItem.Preview2">
           <item name="widgetTitle">Fake title 2</item>
           <item name="widgetContent">Fake content 2</item>
       </style>
   
   </resources>
   

4. Wenden 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_height="wrap_content" ...>
   
       <include layout="@layout/widget_view" ... />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview1" />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview2" />
   
   </LinearLayout>