Widget optimieren

Compose ausprobieren

Jetpack Compose ist das empfohlene UI-Toolkit für Android. Informationen zum Erstellen von Widgets mit APIs im Compose-Stil.

Jetpack Glance →

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

Dynamische Farben verwenden

Ab Android 12 kann ein Widget die Farben des Gerätethemas für Schaltflächen, Hintergründe und andere Komponenten verwenden. Das sorgt für flüssigere Übergänge und Einheitlichkeit bei verschiedenen Widgets.

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

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

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

Sobald das Theme im Root-Layout festgelegt ist, können Sie die dynamischen Farben im Root-Layout oder in einem seiner untergeordneten Elemente mit allgemeinen Farbattributen abrufen.

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

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

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

<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 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 mit dem Material 3-Theme:

<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 Sprachbefehle von Nutzern anzeigen. Wenn Sie Ihr Widget so konfigurieren, dass es auf integrierte Intents (Built-in Intents, BIIs) reagiert, kann Ihre App Widgets proaktiv auf Assistant-Oberflächen wie Android und Android Auto anzeigen. Nutzer haben die Möglichkeit, von Assistant angezeigte Widgets an ihren Launcher anzupinnen, um die zukünftige Interaktion zu fördern.

Sie können beispielsweise das Widget für die Trainingszusammenfassung für Ihre Trainings-App so konfigurieren, dass es die Sprachbefehle des Nutzers erfüllt, die die GET_EXERCISE_OBSERVATION-BII auslösen. Assistant zeigt Ihr Widget proaktiv an, wenn Nutzer diesen BII durch Anfragen wie Hey Google, wie viele Kilometer bin ich diese Woche in Beispiel-App gelaufen? auslösen.

Es gibt Dutzende von BIIs, die verschiedene Kategorien von Nutzerinteraktionen abdecken. So können fast alle Android-Apps ihre Widgets für die Sprachsteuerung optimieren. Weitere Informationen

Widget-Auswahl in Ihrer App verbessern

In Android 12 können Sie skalierte Widget-Vorschaubilder und Widget-Beschreibungen hinzufügen. Mit Android 15 können Sie die Widget-Auswahl für Ihre App mit generierten Widget-Vorschaubildern verbessern.

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.

Generierte Widget-Vorschauen zur Widget-Auswahl hinzufügen

Apps müssen den Wert compileSdk in der Moduldatei build.gradle auf 35 oder höher festlegen, um RemoteViews für die Widget-Auswahl unter Android 15 oder höher bereitstellen zu können. So können Apps die Inhalte in der Auswahl aktualisieren, damit sie besser dem entsprechen, was der Nutzer sieht.

Apps können die Methoden AppWidgetManager, setWidgetPreview und getWidgetPreview verwenden, um das Erscheinungsbild ihrer Widgets mit aktuellen und personalisierten Informationen zu aktualisieren.

Aktualisierte Vorschau mit Jetpack Glance generieren

Glance.compose führt eine Komposition aus. Daher werden im Body Ihres Composables keine suspend-Funktionen, Flows oder ähnliche asynchrone 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 die Build-Einstellung compileSdk 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 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.

Empfohlene Vorgehensweisen zum Erstellen genauer 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>

Wenn Sie eine genaue Vorschau anzeigen möchten, können Sie das tatsächliche Widget-Layout mit Standardwerten direkt angeben. 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 Vorgehensweisen für komplexere Vorschauen mit ListView, GridView oder StackView finden Sie unter Genaue Vorschauen mit dynamischen Elementen erstellen.

Abwärtskompatibilität mit skalierbaren Widget-Vorschaubildern

Wenn Sie möchten, dass in der Widget-Auswahl unter Android 11 (API-Level 30) oder niedriger Vorschauen Ihres Widgets angezeigt werden, 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 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.

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

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

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

Weichere Übergänge aktivieren

Ab Android 12 bieten Launcher 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 zu identifizieren:

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

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

RemoteViews zur Laufzeit ändern

Ab Android 12 können Sie mehrere RemoteViews-Methoden nutzen, mit denen sich RemoteViews-Attribute zur Laufzeit ändern lassen. 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.

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