Widget optimieren

Auf dieser Seite finden Sie Details zu optionalen Widget-Erweiterungen, die ab Android 12 (API-Level 31) verfügbar sind. Diese Funktionen sind optional, aber sie lassen sich ganz einfach implementieren und verbessern die Nutzerfreundlichkeit des Widgets.

Dynamische Farben verwenden

Ab Android 12 können Widgets die Farben des Gerätedesigns für Schaltflächen, Hintergründe und andere Komponenten verwenden. Dies sorgt für reibungslosere Übergänge und Konsistenz über verschiedene Widgets hinweg.

Es gibt zwei Möglichkeiten, dynamische Farben zu erzielen:

Nachdem das Design im Stammlayout festgelegt wurde, können Sie gängige Farbattribute im Stammelement oder in einem seiner untergeordneten Elemente verwenden, um die dynamischen Farben zu übernehmen.

Beispiele für Farbattribute:

  • ?attr/primary
  • ?attr/primaryContainer
  • ?attr/onPrimary
  • ?attr/onPrimaryContainer

Im folgenden Beispiel mit dem Material 3-Design ist die Designfarbe des Geräts „purpur“. Die Akzentfarbe und der Widget-Hintergrund passen sich an den hellen und den dunklen Modus an, wie in den Abbildungen 1 und 2 zu sehen.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>
Widget im hellen Design
Abbildung 1: Widget im hellen Design.
Widgets im dunklen Design
Abbildung 2: Widget im dunklen Design

Abwärtskompatibilität für dynamische Farben

Dynamische Farben sind nur auf Geräten mit Android 12 oder höher verfügbar. Wenn Sie ein benutzerdefiniertes Design für niedrigere Versionen bereitstellen möchten, erstellen Sie ein Standarddesign mit Ihren benutzerdefinierten Farben und einem neuen Qualifier (values-v31) mit den Standarddesignattributen.

Hier ist ein Beispiel für das Thema Material 3:

/values/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

/values-v31/styles.xml

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

/layout/my_widget_layout.xml

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

Sprachunterstützung aktivieren

Mit App-Aktionen kann Google Assistant Widgets als Antwort auf relevante Sprachbefehle von Nutzern anzeigen. Wenn Sie Ihr Widget so konfigurieren, dass es auf vordefinierte Intents (BIIs) reagiert, kann Ihre App proaktiv Widgets auf Assistant-Oberflächen wie Android und Android Auto anzeigen. Nutzer können von Assistant angezeigte Widgets an ihren Launcher anpinnen, um zukünftige Interaktionen zu fördern.

Sie können beispielsweise das Widget „Trainingsübersicht“ für Ihre Trainings-App so konfigurieren, dass die Sprachbefehle der Nutzer, die die BII GET_EXERCISE_OBSERVATION auslösen, ausgeführt werden. Assistant zeigt Ihr Widget proaktiv an, wenn Nutzer diese BII auslösen, indem sie Anfragen wie „Hey Google, wie viele Kilometer habe ich diese Woche mit der Beispiel-App zurückgelegt?“ stellen.

Es gibt Dutzende BIIs, die mehrere Kategorien der Nutzerinteraktion abdecken, sodass nahezu jede Android-App ihre Voice-Widgets verbessern kann. Weitere Informationen finden Sie unter App-Aktionen in Android-Widgets einbinden.

Widgetauswahl in Ihrer App verbessern

Unter Android 12 können Sie skalierte Widget-Vorschauen und Widget-Beschreibungen hinzufügen. Mit Android 15 können Sie die Auswahl von Widgets für Ihre App mithilfe von generierten Widget-Vorschauen verbessern.

Um die Nutzerfreundlichkeit der Widgetauswahl Ihrer App zu verbessern, sollten Sie auf Geräten mit Android 15 und höher eine generierte Widget-Vorschau bereitstellen, auf Geräten mit Android 12 bis Android 14 eine skalierte Widget-Vorschau (durch Angabe einer previewLayout) und auf Geräten mit früheren Versionen eine previewImage.

Generierte Widget-Vorschauen zur Widget-Auswahl hinzufügen

Für Apps muss der compileSdk-Wert in der build.gradle-Datei des Moduls auf 35 oder höher gesetzt werden, damit auf Geräten mit Android 15 oder höher RemoteViews für die Widget-Auswahl bereitgestellt werden kann. Das bedeutet, dass Apps die Inhalte in der Auswahl aktualisieren können, damit sie besser zu dem passen, was der Nutzer sieht.

Mit den Methoden AppWidgetManager, setWidgetPreview und getWidgetPreview können Apps das Aussehen ihrer Widgets mit aktuellen und personalisierten Informationen aktualisieren.

Aktualisierte Vorschau mit Jetpack Glance generieren

Glance.compose führt eine Komposition aus. Daher werden im Body des Composeables keine Suspend-Funktionen, ‑Abläufe oder ähnlichen asynchronen Aufrufe verwendet. Stattdessen müssen Sie konstante Daten verwenden.

Im folgenden Beispiel wird Jetpack Glance verwendet, um eine aktualisierte Vorschau zu generieren. Für compileSdk ist die Build-Einstellung 35 oder höher erforderlich, damit setWidgetPreview in diesem Snippet als Methode angezeigt wird.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)

AppWidgetSnippets.kt

Aktualisierte Vorschau ohne Jetpack Glance generieren

Sie können RemoteViews auch ohne Glance verwenden. Im folgenden Beispiel wird eine XML-Widget-Layoutressource geladen und als Vorschau festgelegt. Damit setWidgetPreview in diesem Snippet als Methode angezeigt wird, ist die Build-Einstellung „compilSdk“ mit mindestens 35 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 Widget-Vorschau in der Widget-Auswahl skalierbar. Sie stellen es als XML-Layout bereit, das auf die Standardgröße des Widgets festgelegt ist. Bisher war die Widget-Vorschau eine statische Zeichnen-Ressource. In einigen Fällen spiegelte die Vorschau nicht genau wider, wie Widgets aussehen, wenn sie dem Startbildschirm hinzugefügt werden.

Wenn Sie skalierbare Widget-Vorschauen implementieren möchten, verwenden Sie stattdessen das previewLayout-Attribut des appwidget-provider-Elements, um ein XML-Layout anzugeben:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

Wir empfehlen, dasselbe Layout wie das eigentliche Widget zu verwenden und realistische Standard- oder Testwerte festzulegen. Die meisten Apps verwenden dieselbe previewLayout und initialLayout. Im folgenden Abschnitt dieser Seite finden Sie eine Anleitung zum Erstellen korrekter Vorschaulayouts.

Wir empfehlen, sowohl das Attribut previewLayout als auch previewImage anzugeben, damit deine 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.

Empfohlene Vorgehensweisen für die Erstellung präziser Vorschauen

Wenn Sie skalierbare Widget-Vorschauen implementieren möchten, verwenden Sie das Attribut previewLayout des Elements appwidget-provider, um ein XML-Layout anzugeben:

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
Ein Bild, das eine Widget-Vorschau zeigt
Abbildung 3. Eine Widget-Vorschau, die standardmäßig in einem 3 × 3-Bereich angezeigt wird, aber aufgrund ihres XML-Layouts in einen 3 × 1-Bereich passt.

Wenn Sie eine genaue Vorschau anzeigen möchten, können Sie dem tatsächlichen Widget-Layout direkt Standardwerte zuweisen. Gehen Sie dazu so vor:

  • android:text="@string/my_widget_item_fake_1" für TextView-Elemente festlegen

  • Festlegen eines Standard- oder Platzhalterbilds oder -symbols, z. B. android:src="@drawable/my_widget_icon", für ImageView-Komponenten.

Ohne Standardwerte werden in der Vorschau möglicherweise falsche oder leere Werte angezeigt. Ein wichtiger Vorteil dieses Ansatzes besteht darin, dass du lokalisierte Vorschauinhalte bereitstellen kannst.

Empfohlene Ansätze für komplexere Vorschauen, die ListView, GridView oder StackView enthalten, finden Sie unter Genaue Vorschauen mit dynamischen Elementen erstellen.

Abwärtskompatibilität mit skalierbaren Widget-Vorschauen

Wenn Sie in Widget-Auswahlen unter Android 11 (API-Level 30) oder niedriger Vorschaubilder Ihres Widgets anzeigen lassen möchten, geben Sie das Attribut previewImage an.

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

Dem Widget einen Namen geben

Widgets müssen einen eindeutigen Namen haben, wenn sie in der Widget-Auswahl angezeigt werden.

Die Namen von Widgets werden aus dem Attribut label des Elements receiver des Widgets in der Datei AndroidManifest.xml geladen.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

Beschreibung für das Widget hinzufügen

Ab Android 12 müssen Sie eine Beschreibung für die Widget-Auswahl angeben, die für Ihr Widget angezeigt werden soll.

Ein Bild, das eine Widget-Auswahl mit einem Widget und seiner Beschreibung zeigt
Abbildung 4: Beispiel für eine Widgetauswahl mit einem Widget und seiner Beschreibung

Geben Sie mit dem Attribut description des Elements &lt;appwidget-provider&gt; eine Beschreibung für Ihr Widget an:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

Das Attribut descriptionRes kann auch in früheren Android-Versionen verwendet werden, wird aber in der Widget-Auswahl ignoriert.

Bessere Übergänge

Ab Android 12 sorgen Launcher für einen reibungsloseren Übergang, wenn ein Nutzer Ihre App über ein Widget startet.

Wenn Sie diesen verbesserten Übergang aktivieren möchten, verwenden Sie @android:id/background oder android.R.id.background, um das Hintergrundelement anzugeben:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

Ihre App kann @android:id/background in älteren Android-Versionen verwenden, ohne dass es zu Fehlern kommt. Die Funktion wird jedoch ignoriert.

Laufzeitänderung von RemoteViews verwenden

Ab Android 12 stehen Ihnen mehrere RemoteViews-Methoden zur Verfügung, mit denen sich die Laufzeit von RemoteViews-Attributen ändern lässt. Eine vollständige Liste der hinzugefügten Methoden findest du in der RemoteViews API-Referenz.

Das folgende Codebeispiel zeigt, wie einige dieser Methoden verwendet werden.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);