Einfaches Widget erstellen

Compose ausprobieren
Jetpack Compose ist das empfohlene UI-Toolkit für Android. Hier erfahren Sie, wie Sie Widgets mit APIs im Compose-Stil erstellen.
Jetpack Glance →

App-Widgets sind Miniaturansichten von Apps, die Sie in andere Apps wie den Startbildschirm einbetten und regelmäßig aktualisieren lassen können. Diese Ansichten werden auf der Benutzeroberfläche als Widgets bezeichnet. Sie können sie mit einem App-Widget-Anbieter (oder Widget-Anbieter) veröffentlichen. Eine App-Komponente, die andere Widgets enthält, wird als App-Widget-Host (oder Widget-Host) bezeichnet. Abbildung 1 zeigt ein Beispiel für ein Musik-Widget:

Beispiel für ein Musik-Widget
Abbildung 1. Beispiel für ein Musik-Widget

In diesem Dokument wird beschrieben, wie Sie ein Widget mithilfe eines Widget-Anbieters veröffentlichen. Weitere Informationen zum Erstellen eines eigenen AppWidgetHost zum Hosten von App-Widgets finden Sie unter Widget-Host erstellen.

Informationen zum Design von Widgets finden Sie unter App-Widgets – Übersicht.

Widget-Komponenten

Zum Erstellen eines Widgets benötigen Sie die folgenden grundlegenden Komponenten:

AppWidgetProviderInfo-Objekt
Beschreibt die Metadaten für ein Widget, z. B. das Layout, die Updatehäufigkeit und die AppWidgetProvider-Klasse des Widgets. AppWidgetProviderInfo wird in XML definiert, wie in diesem Dokument beschrieben.
Klasse AppWidgetProvider
Definiert die grundlegenden Methoden, mit denen Sie programmatisch mit dem Widget interagieren können. Darüber erhalten Sie Broadcasts, wenn das Widget aktualisiert, aktiviert, deaktiviert oder gelöscht wird. Sie deklarieren AppWidgetProvider im Manifest und implementieren es dann wie in diesem Dokument beschrieben.
Layout ansehen
Defines the initial layout for the widget. Das Layout wird in XML definiert, wie in diesem Dokument beschrieben.

Abbildung 2 zeigt, wie diese Komponenten in den gesamten Verarbeitungsprozess für App-Widgets passen.

Verarbeitungsablauf für App-Widgets
Abbildung 2: Ablauf der Verarbeitung von App-Widgets.

Wenn für Ihr Widget eine Nutzerkonfiguration erforderlich ist, implementieren Sie die Aktivität zur Konfiguration von App-Widgets. Mit dieser Aktivität können Nutzer Widget-Einstellungen ändern, z. B. die Zeitzone für ein Uhr-Widget.

Außerdem empfehlen wir die folgenden Verbesserungen: flexible Widget-Layouts, verschiedene Verbesserungen, erweiterte Widgets, Sammlungs-Widgets und Erstellen eines Widget-Hosts.

AppWidgetProviderInfo-XML deklarieren

Das Definieren der Metadateneinstellungen (z. B. Standardzellengrößen, Größenänderungseinschränkungen und Aktualisierungshäufigkeiten) ist sowohl bei herkömmlichen Ansichten als auch bei Glance-basierten Widgets identisch.

Informationen zum Definieren und Konfigurieren der XML-Datei mit Metadaten finden Sie in der Glance-Dokumentation im Compose-first-Abschnitt AppWidgetProviderInfo-XML deklarieren.

AppWidgetProvider-Klasse zum Verarbeiten von Widget-Broadcasts verwenden

Die Übertragungsempfänger-Mechanismen, Manifestdeklarationsfilter und Lifecycle-Event-Schleifen der Plattform sind vereinheitlicht. Bei der Compose-first-Entwicklung werden diese Broadcasts mit dem Wrapper GlanceAppWidgetReceiver orchestriert.

Informationen dazu, wie Sie Ihren Receiver im Manifest registrieren und Hilt-kompatible Lifecycle-Überschreibungen implementieren, finden Sie in der Glance-Dokumentation im Abschnitt Use the AppWidgetProvider class to handle broadcasts (Die AppWidgetProvider-Klasse zum Verarbeiten von Broadcasts verwenden).

Widget-Layout erstellen

Sie müssen ein anfängliches Layout für Ihr Widget in XML definieren und im Verzeichnis res/layout/ des Projekts speichern. Weitere Informationen finden Sie in den Designrichtlinien.

Wenn Sie mit Layouts vertraut sind, ist das Erstellen des Widget-Layouts ganz einfach. Widget-Layouts basieren jedoch auf RemoteViews, das nicht jede Art von Layout oder View-Widget unterstützt. Sie können keine benutzerdefinierten Ansichten oder Unterklassen der von RemoteViews unterstützten Ansichten verwenden.

RemoteViews unterstützt auch ViewStub, ein unsichtbares View mit der Größe null, mit dem Sie Layoutressourcen zur Laufzeit verzögert aufblähen können.

Unterstützung für zustandsorientiertes Verhalten

In Android 12 wird die Unterstützung für zustandsbehaftetes Verhalten mit den folgenden vorhandenen Komponenten hinzugefügt:

Das Widget ist weiterhin zustandslos. Ihre App muss den Status speichern und sich für Statusänderungsereignisse registrieren.

Beispiel für ein Einkaufslisten-Widget mit zustandsorientiertem Verhalten
Abbildung 3: Beispiel für zustandsorientiertes Verhalten.

Im folgenden Codebeispiel wird gezeigt, wie Sie diese Komponenten implementieren.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

Stellen Sie zwei Layouts bereit: eines für Geräte mit Android 12 oder höher in res/layout-v31 und das andere für Geräte mit Android 11 oder niedriger im Standardordner res/layout.

Abgerundete Ecken implementieren

Die Berechnung des äußeren Hintergrunds und der inneren proportionalen Radien ist Standard und wird gemeinsam genutzt. Bei der Compose-First-Entwicklung kann dies dynamisch in Kotlin zusammen mit benutzerdefinierten Designressourcen festgelegt werden.

Informationen zum Implementieren von Eckenradien oder zum Einrichten dynamischer Stile für ältere Android-Geräte finden Sie im Abschnitt Abgerundete Ecken implementieren in der Glance-Dokumentation.