Widget optimieren

Diese Seite enthält Details zu optionalen Widget-Verbesserungen, die ab Android 12 (API-Level 31) verfügbar sind. Diese Funktionen sind optional, lassen sich aber ganz einfach implementieren und verbessern.

Dynamische Farben verwenden

Ab Android 12 kann ein Widget die Gerätedesignfarben 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 erhalten:

• Verwenden Sie im Stammlayout das Standarddesign des Systems (@android:style/Theme.DeviceDefault.DayNight).

• Du kannst das Material 3-Design (Theme.Material3.DynamicColors.DayNight) aus der Bibliothek Material Components for Android verwenden, die ab Material Components for Android Version 1.6.0 verfügbar ist.

Sobald das Design im Stammlayout festgelegt ist, können Sie allgemeine Farbattribute im Stamm oder in einem seiner untergeordneten Elemente verwenden, um die dynamischen Farben abzurufen.

Hier einige Beispiele für Farbattribute, die Sie verwenden können:

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

Im folgenden Beispiel, in dem das Material 3-Design verwendet wird, lautet die Designfarbe des Geräts „Lila“. Die Akzentfarbe und der Widget-Hintergrund passen sich an den hellen und den dunklen Modus an, wie in den Abbildungen 1 und 2 dargestellt.

<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>

Abwärtskompatibilität für dynamische Farben

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

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

<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>

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

<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 Actions kann Google Assistant Widgets als Reaktion auf relevante Nutzerbefehle anzeigen. Wenn du dein Widget so konfigurierst, dass es auf integrierte Intents (BIIs) reagiert, können in deiner App Widgets auf Assistant-Oberflächen wie Android und Android Auto proaktiv angezeigt werden. Nutzer haben die Möglichkeit, von Assistant angezeigte Widgets an ihren Launcher anzupinnen, um zukünftige Interaktionen zu fördern.

Du kannst beispielsweise das Widget mit der Trainingszusammenfassung für deine Trainings-App so konfigurieren, dass die Sprachbefehle des Nutzers ausgeführt werden, die den BII GET_EXERCISE_OBSERVATION auslösen. Assistant zeigt dein Widget proaktiv an, wenn Nutzer diesen BII auslösen, indem sie Anfragen wie „Hey Google, wie viele Kilometer bin ich diese Woche in ExampleApp gelaufen?“ stellen.

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

Die Widget-Auswahl deiner App verbessern

Mit Android 12 kannst du die Widget-Auswahl für deine App verbessern, indem du dynamische Widget-Vorschauen und Widget-Beschreibungen hinzufügst.

Skalierbare Widget-Vorschauen zur Widget-Auswahl hinzufügen

Ab Android 12 ist die in der Widget-Auswahl angezeigte Widget-Vorschau skalierbar. Sie stellen sie als XML-Layout bereit, das auf die Standardgröße des Widgets eingestellt ist. Bisher war die Widget-Vorschau eine statische Drawable-Ressource, die in einigen Fällen zu Vorschauen führte, die nicht genau widerspiegeln, wie Widgets angezeigt wurden, wenn sie dem Startbildschirm hinzugefügt werden.

Wenn du skalierbare Widget-Vorschauen implementieren möchtest, verwende stattdessen das Attribut previewLayout des Elements appwidget-provider, um ein XML-Layout bereitzustellen:

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

Wir empfehlen, dasselbe Layout wie das eigentliche Widget mit realistischen Standard- oder Testwerten zu verwenden. Die meisten Apps verwenden dieselben previewLayout und initialLayout. Eine Anleitung zum Erstellen genauer Vorschaulayouts finden Sie im folgenden Abschnitt auf dieser Seite.

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 Ansätze zum Erstellen genauer Vorschauen

Wenn du skalierbare Widget-Vorschauen implementieren möchtest, verwende das Attribut previewLayout des appwidget-provider-Elements, um ein XML-Layout anzugeben:

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

Wenn du eine genaue Vorschau sehen möchtest, kannst du das eigentliche Widget-Layout direkt mit Standardwerten bereitstellen. Gehe dazu so vor:

• Für TextView-Elemente wird android:text="@string/my_widget_item_fake_1" festgelegt.

• 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 erstellen, die dynamische Elemente enthalten.

Abwärtskompatibilität mit skalierbaren Widget-Vorschauen

Damit in der Widget-Auswahl unter Android 11 (API-Level 30) oder niedriger eine Vorschau des Widgets angezeigt wird, musst du das Attribut previewImage angeben.

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

Beschreibung für das Widget hinzufügen

Gib ab Android 12 eine Beschreibung für die Widget-Auswahl an, die für dein Widget angezeigt werden soll.

Gib mithilfe des Attributs description des Elements <appwidget-provider> eine Beschreibung für dein 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 von der Widget-Auswahl ignoriert.

Reibungslosere Übergänge ermöglichen

Ab Android 12 ermöglichen Launcher einen reibungsloseren Übergang, wenn ein Nutzer deine App über ein Widget startet.

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

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

Deine App kann @android:id/background unter früheren Android-Versionen verwenden, ohne dass Probleme auftreten, sie wird aber 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 finden Sie in der API-Referenz zu RemoteViews.

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

// 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)

// 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);