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:

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

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

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>

Abbildung 1: Widget im hellen Design

Abbildung 2: Widget im dunklen Design

Tipp :Wir empfehlen, das Material 3-Design zu verwenden, um die Material Design-Richtlinien für Konsistenz zwischen Geräten und Abwärtskompatibilität einzuhalten.

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

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

Hinweis: Unter Stile und Designs finden Sie eine ausführliche Anleitung zum Umgang mit verschiedenen Stilen, Farben, Attributen und Designs.

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 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 früheren 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 mindestens 35 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:

<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 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 Attribut previewLayout des Elements appwidget-provider, um ein XML-Layout anzugeben:

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

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

  Hinweis: Werte, die mit dem tools-Tag festgelegt wurden, z. B. tools:text="@string/my_wdiget_item_fake_1", werden in der Vorschau nicht angezeigt.

• 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, 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.

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.

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

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:

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

Hinweis :Fassen Sie sich kurz. Es gibt keine Zeichenbeschränkung, aber die Darstellung und der verfügbare Platz für die Beschreibung können je nach Gerät variieren.

Sie können das Attribut descriptionRes in früheren Android-Versionen verwenden, es wird jedoch von der Widgetauswahl 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.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

Warnung :Verwenden Sie keine Broadcast-Trampoline. Ab Android 12 kann eine App weiterhin eine Aktivität über einen Übertragungsempfänger oder Dienst starten, wenn sie über die PendingIntent eines Widget-Klicks initiiert wird. Die neue App-Animation wird jedoch nicht für Apps verwendet, die über einen Broadcast-Empfänger oder -Dienst gestartet werden, was zu einer schlechten Nutzererfahrung führt.

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 können Sie mehrere RemoteViews-Methoden nutzen, die eine Laufzeitänderung von RemoteViews-Attributen ermöglichen. 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);