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. So werden Übergänge flüssiger und die verschiedenen Widgets sind einheitlicher.

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.

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

      ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />
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 ein Beispiel mit dem Material 3-Design:

/values/styles.xml


   name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    
     name="android:colorBackground">@color/my_background_color

/values-v31/styles.xml


  
   name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />

/layout/my_widget_layout.xml


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

Sprachunterstützung aktivieren

Mit App-Aktionen kann Google Assistant Widgets als Reaktion 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 Widgets anpinnen, die von Assistant angezeigt werden, 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 ausgeführt werden, die die BII GET_EXERCISE_OBSERVATION auslösen. 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 von BIIs, die mehrere Kategorien der Nutzerinteraktion abdecken. So können fast alle Android-Apps ihre Widgets für die Sprachsteuerung optimieren. 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 älteren Versionen eine previewImage.

Der Widget-Auswahl generierte Widget-Vorschauen hinzufügen

In der Moduldatei build.gradle muss der Wert für compileSdk auf 35 oder höher festgelegt sein, damit auf Geräten mit Android 15 oder höher RemoteViews für die Widgetauswahl angegeben 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 die Anzeige von setWidgetPreview als Methode in diesem Snippet ist eine compileSdk-Build-Einstellung von 35 oder höher erforderlich.

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. Für die Anzeige von setWidgetPreview als Methode in diesem Snippet ist die Build-Einstellung „compileSdk“ mit dem Wert „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 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:

    android:previewLayout="@layout/my_widget_preview">

Wir empfehlen, dasselbe Layout wie das eigentliche Widget zu verwenden, mit realistischen Standard- oder Testwerten. 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 previewLayout- als auch das previewImage-Attribut 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.

Empfohlene Vorgehensweisen für die Erstellung präziser Vorschauen

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

    ...
    android:previewLayout="@layout/my_widget_preview">
Ein Bild mit einer Widget-Vorschau
Abbildung 3: Eine Widget-Vorschau, die standardmäßig in einem Bereich von 3 × 3 Pixeln angezeigt wird, aber aufgrund ihres XML-Layouts auch in einem Bereich von 3 × 1 Pixeln Platz findet.

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 ist, dass Sie lokalisierte Vorschauinhalte bereitstellen können.

Empfohlene Ansätze für komplexere Vorschauen mit ListView, GridView oder StackView 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 Erscheinungsbild des Widgets ändern, aktualisieren Sie das Vorschaubild.

Widget einen Namen geben

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

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


     ….

Beschreibung für das Widget hinzufügen

Ab Android 12 müssen Sie für die Widgetauswahl eine Beschreibung für Ihr Widget angeben.

Ein Bild mit einer Widget-Auswahl, in der ein Widget und seine Beschreibung zu sehen sind
Abbildung 4: Beispiel für eine Widgetauswahl mit einem Widget und seiner Beschreibung

Geben Sie mit dem Attribut description des Elements <appwidget-provider> eine Beschreibung für Ihr Widget an:

    android:description="@string/my_widget_description">

Sie können das Attribut descriptionRes in früheren Android-Versionen verwenden, es wird jedoch von der Widget-Auswahl ignoriert.

Für flüssigere Übergänge sorgen

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

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.
    android:id="@android:id/background">

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

Laufzeitänderung von RemoteViews verwenden

Ab Android 12 können Sie mehrere RemoteViews-Methoden nutzen, die eine Laufzeitänderung von RemoteViews-Attributen ermöglichen. Eine vollständige Liste der hinzugefügten Methoden finden Sie 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);