Einfaches Widget erstellen

Compose ausprobieren
Jetpack Compose ist das empfohlene UI-Toolkit für Android. Hier erfährst du, wie du Widgets mit Compose-ähnlichen APIs erstellst.
Jetpack Glance →

App-Widgets sind Miniatur-App-Ansichten, die Sie in andere Apps einbetten können, z. B. in den Startbildschirm, und die regelmäßig aktualisiert werden. Diese Ansichten werden auf der Benutzeroberfläche als Widgets bezeichnet. Sie können ein Widget 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 mit einem Widget-Anbieter veröffentlichen. Weitere Informationen zum Erstellen eines eigenen AppWidgetHost zum Hosten von App-Widgets finden Sie unter Widget-Host erstellen.

Informationen zum Entwerfen Ihres 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 des Widgets, die Aktualisierungshäufigkeit und die Klasse AppWidgetProvider. 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. Dadurch erhältst du 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
Definiert das anfängliche Layout für das Widget. Das Layout wird in XML definiert, wie in diesem Dokument beschrieben.

Abbildung 2 zeigt, wie diese Komponenten in den gesamten Verarbeitungsablauf von App-Widgets passen.

Verarbeitungsablauf für App-Widgets
Abbildung 2: Verarbeitungsablauf für App-Widgets

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

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

AppWidgetProviderInfo-XML deklarieren

Die Definition der Metadateneinstellungen (z. B. Standardzellengrößen, Einschränkungen bei der Größenanpassung und Updatehäufigkeiten) ist bei herkömmlichen Ansichten und Glance-basierten Widgets genau gleich.

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

Widget-Broadcasts mit der Klasse „AppWidgetProvider“ verarbeiten

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

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

Widget-Layout erstellen

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

Das Erstellen des Widget-Layouts ist einfach, wenn Sie mit Layouts vertraut sind. Beachten Sie jedoch, dass Widget-Layouts auf RemoteViews basieren, das nicht alle Arten von Layout- oder Ansichts-Widgets unterstützt. Sie können keine benutzerdefinierten Ansichten oder Unterklassen der Ansichten verwenden, die von RemoteViews unterstützt werden.

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

Unterstützung für zustandsorientiertes Verhalten

Android 12 bietet Unterstützung für zustandsorientiertes Verhalten mit den folgenden vorhandenen Komponenten:

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.

Das folgende Codebeispiel zeigt, wie diese Komponenten implementiert werden.

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

Stelle zwei Layouts bereit: eines für Geräte mit Android 12 oder höher in res/layout-v31 und eines 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. In 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.