Einfaches Widget erstellen

Der Compose-Ansatz
Jetpack Compose ist das empfohlene UI-Toolkit für Android. Informationen zum Erstellen von Widgets mit Compose-APIs.
Jetpack Glance →

App-Widgets sind Miniaturansichten von Apps, die in andere Apps wie den Startbildschirm eingebettet werden können und regelmäßig aktualisiert werden. Diese Ansichten werden in 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 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 Designen von Widgets finden Sie unter Übersicht über App-Widgets.

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 Updatehäufigkeit und die Klasse AppWidgetProvider. AppWidgetProviderInfo wird in XML definiert, wie in diesem Dokument beschrieben.
AppWidgetProvider -Klasse
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
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 für App-Widgets passen.

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

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

  • Ab Android 12 (API-Level 31) können Sie eine Standardkonfiguration bereitstellen und Nutzern erlauben, das Widget später neu zu konfigurieren. Weitere Informationen finden Sie unter Use the widget's default configuration und Enable users to reconfigure placed widgets.
  • Unter Android 11 (API-Level 30) oder niedriger wird diese Aktivität jedes Mal gestartet, wenn der Nutzer das Widget seinem Startbildschirm hinzufügt.

Wir empfehlen außerdem 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änderungsbeschränkungen und Aktualisierungshäufigkeiten) ist sowohl für herkömmliche Ansichten als auch für Glance-basierte Widgets identisch.

Informationen zum Definieren und Konfigurieren der XML-Datei für Metadaten finden Sie im Abschnitt AppWidgetProviderInfo-XML deklarieren (Compose-first) in der Glance Dokumentation.

AppWidgetProvider-Klasse zum Verarbeiten von Widget-Broadcasts verwenden

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

Informationen zum Registrieren des Receivers im Manifest und zum Implementieren von Hilt-kompatiblen Lebenszyklusüberschreibungen finden Sie im Abschnitt AppWidgetProvider-Klasse zum Verarbeiten von Broadcasts verwenden (Compose-first) in der Glance Dokumentation.

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.

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

RemoteViews unterstützt auch ViewStub, eine unsichtbare View mit der Größe 0, mit der Sie Layoutressourcen zur Laufzeit verzögert aufrufen 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 Sie diese Komponenten implementieren.

Kotlin

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

Java

// 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 standardmäßig und wird gemeinsam verwendet. Bei der Compose-first-Entwicklung kann dies in Kotlin zusammen mit benutzerdefinierten Designressourcen dynamisch festgelegt werden.

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