Einfaches Widget erstellen

App-Widgets sind Miniaturansichten von Apps, 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 sie über einen 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:

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 App-Widget-Host erstellen.

Informationen zum Entwerfen Ihres Widgets finden Sie unter 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, die Aktualisierungshäufigkeit und die AppWidgetProvider-Klasse des Widgets. AppWidgetProviderInfo ist in XML definiert, wie in diesem Dokument beschrieben.

AppWidgetProvider-Klasse

Definiert die grundlegenden Methoden, mit denen Sie programmatisch mit dem Widget interagieren können. Über diesen Dienst erhalten Sie Benachrichtigungen, 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 ursprü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 des App-Widgets passen.

Abbildung 2: Ablauf der App-Widget-Verarbeitung

Hinweis :Android Studio kann automatisch eine Reihe von AppWidgetProviderInfo-, AppWidgetProvider- und Ansichtslayoutdateien erstellen. Wählen Sie Neu > Widget > App-Widget aus.

Wenn für Ihr Widget eine Nutzerkonfiguration erforderlich ist, implementieren Sie die Aktivität „App-Widget konfigurieren“. Bei dieser Aktivität können Nutzer Widget-Einstellungen ändern, z. B. die Zeitzone für ein Uhren-Widget.

• Ab Android 12 (API-Level 31) können Sie eine Standardkonfiguration angeben und Nutzern die Möglichkeit geben, das Widget später neu zu konfigurieren. Weitere Informationen finden Sie unter Standardkonfiguration des Widgets verwenden und Nutzer zulassen, platzierte Widgets neu zu konfigurieren.
• 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 einen Widget-Host erstellen.

AppWidgetProviderInfo-XML-Datei deklarieren

Das AppWidgetProviderInfo-Objekt definiert die wesentlichen Eigenschaften eines Widgets. Definieren Sie das AppWidgetProviderInfo-Objekt in einer XML-Ressourcendatei mit einem einzelnen <appwidget-provider>-Element und speichern Sie es im Ordner res/xml/ des Projekts.

Das ist im folgenden Beispiel zu sehen:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Attribute für die Größe von Widgets

Auf dem Standard-Startbildschirm werden Widgets im Fenster anhand eines Rasters mit Zellen mit definierter Höhe und Breite positioniert. Auf den meisten Startbildschirmen können Widgets nur eine Größe haben, die ein ganzzahliges Vielfaches der Rasterzellen ist, z. B. zwei Zellen horizontal und drei Zellen vertikal.

Mit den Attributen für die Widget-Größe können Sie eine Standardgröße für das Widget festlegen und eine Unter- und Obergrenze für die Größe des Widgets angeben. In diesem Zusammenhang ist die Standardgröße eines Widgets die Größe, die es hat, wenn es dem Startbildschirm zum ersten Mal hinzugefügt wird.

In der folgenden Tabelle werden die <appwidget-provider>-Attribute beschrieben, die sich auf die Größe von Widgets beziehen:

Attribute und Beschreibung
targetCellWidth und targetCellHeight (Android 12), minWidth und minHeight	Ab Android 12 geben die Attribute targetCellWidth und targetCellHeight die Standardgröße des Widgets in Rasterzellen an. Diese Attribute werden unter Android 11 und niedriger ignoriert und können ignoriert werden, wenn der Startbildschirm kein gitterbasiertes Layout unterstützt. Die Attribute minWidth und minHeight geben die Standardgröße des Widgets in dp an. Wenn die Werte für die Mindestbreite oder -höhe eines Widgets nicht mit den Abmessungen der Zellen übereinstimmen, werden sie auf die nächste Zellengröße aufgerundet. Wir empfehlen, beide Attribute anzugeben – targetCellWidth und targetCellHeight sowie minWidth und minHeight –, damit Ihre App auf minWidth und minHeight zurückgreifen kann, wenn das Gerät des Nutzers targetCellWidth und targetCellHeight nicht unterstützt. Sofern unterstützt, haben die Attribute targetCellWidth und targetCellHeight Vorrang vor den Attributen minWidth und minHeight.
minResizeWidth und minResizeHeight	Geben Sie die absolute Mindestgröße des Widgets an. Diese Werte geben die Größe an, unter der das Widget unlesbar oder anderweitig unbrauchbar ist. Mithilfe dieser Attribute kann der Nutzer die Größe des Widgets auf eine Größe ändern, die kleiner als die Standardgröße des Widgets ist. Das Attribut minResizeWidth wird ignoriert, wenn es größer als minWidth ist oder die horizontale Größenänderung nicht aktiviert ist. Siehe resizeMode. Ebenso wird das Attribut minResizeHeight ignoriert, wenn es größer als minHeight ist oder die vertikale Größenänderung nicht aktiviert ist.
maxResizeWidth und maxResizeHeight	Geben Sie die empfohlene maximale Größe des Widgets an. Wenn die Werte kein Vielfaches der Rasterzellenabmessungen sind, werden sie auf die nächste Zellengröße aufgerundet. Das Attribut maxResizeWidth wird ignoriert, wenn es kleiner als minWidth ist oder die horizontale Größenänderung nicht aktiviert ist. Weitere Informationen finden Sie unter resizeMode. Ebenso wird das Attribut maxResizeHeight ignoriert, wenn es größer als minHeight ist oder die vertikale Größenänderung nicht aktiviert ist. Einführung in Android 12.
resizeMode	Hier werden die Regeln festgelegt, nach denen ein Widget die Größe ändern kann. Mit diesem Attribut können Sie Startbildschirm-Widgets horizontal, vertikal oder in beide Richtungen skalieren. Nutzer halten ein Widget gedrückt, um die Ziehpunkte für die Größe zu sehen, und ziehen dann die horizontalen oder vertikalen Ziehpunkte, um die Größe im Layout-Raster zu ändern. Zulässige Werte für das Attribut resizeMode sind horizontal, vertical und none. Wenn Sie ein Widget horizontal und vertikal skalierbar deklarieren möchten, verwenden Sie horizontal|vertical.

Verwendungsbeispiele

Anhand der folgenden Spezifikationen wird veranschaulicht, wie sich die Attribute in der vorherigen Tabelle auf die Größe des Widgets auswirken:

• Eine Rasterzelle ist 30 dp breit und 50 dp hoch.
• Die folgende Attributspezifikation wird bereitgestellt:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

Ab Android 12:

Verwenden Sie die Attribute targetCellWidth und targetCellHeight als Standardgröße des Widgets.

Die Standardgröße des Widgets ist 2 × 2. Die Größe des Widgets kann auf 2 × 1 oder 4 × 3 verringert oder vergrößert werden.

Android 11 und niedriger:

Verwenden Sie die Attribute minWidth und minHeight, um die Standardgröße des Widgets zu berechnen.

Die Standardbreite ist Math.ceil(80 / 30) = 3.

Standardhöhe = Math.ceil(80 / 50) = 2

Das Widget hat standardmäßig eine Größe von 3 × 2. Die Größe des Widgets kann auf 2 × 1 Pixel oder bis zum Vollbildmodus geändert werden.

Hinweis: Die Berechnung der tatsächlichen Größe des Widgets ist komplexer als die vorherige Formel, da sie auch die Ränder des Widgets und den Abstand zwischen den Rasterzellen enthält.

Zusätzliche Widget-Attribute

In der folgenden Tabelle werden die <appwidget-provider>-Attribute beschrieben, die sich auf andere Eigenschaften als die Größe des Widgets beziehen.

Attribute und Beschreibung
updatePeriodMillis	Hiermit wird festgelegt, wie oft das Widget-Framework ein Update von der AppWidgetProvider anfordert, indem die onUpdate()-Callback-Methode aufgerufen wird. Die Aktualisierung erfolgt nicht garantiert genau zu diesem Zeitpunkt. Wir empfehlen, Updates so selten wie möglich durchzuführen – nicht mehr als einmal pro Stunde –, um den Akku zu schonen. Eine vollständige Liste der Aspekte, die Sie bei der Auswahl eines geeigneten Aktualisierungszeitraums berücksichtigen sollten, finden Sie unter Optimierungen für die Aktualisierung von Widget-Inhalten.
initialLayout	Verweist auf die Layoutressource, die das Widget-Layout definiert.
configure	Hier wird die Aktivität definiert, die gestartet wird, wenn der Nutzer das Widget hinzufügt. So kann er die Widget-Eigenschaften konfigurieren. Weitere Informationen finden Sie unter Nutzern die Konfiguration von Widgets ermöglichen. Ab Android 12 kann Ihre App die Erstkonfiguration überspringen. Weitere Informationen finden Sie unter Standardkonfiguration des Widgets verwenden.
description	Gibt die Beschreibung an, die in der Widget-Auswahl für Ihr Widget angezeigt werden soll. Einführung in Android 12.
previewLayout (Android 12) und previewImage (Android 11 und niedriger)	Ab Android 12 gibt das Attribut previewLayout eine skalierbare Vorschau an, die Sie als XML-Layout mit der Standardgröße des Widgets angeben. Idealerweise ist die als Attribut angegebene Layout-XML-Datei dieselbe wie die des tatsächlichen Widgets mit realistischen Standardwerten. Unter Android 11 oder niedriger gibt das previewImage-Attribut eine Vorschau des Widgets nach der Konfiguration an, die Nutzer sehen, wenn sie das App-Widget auswählen. Wenn Sie kein Symbol angeben, wird Nutzern stattdessen das Launcher-Symbol Ihrer App angezeigt. Dieses Feld entspricht dem Attribut android:previewImage im Element <receiver> in der AndroidManifest.xml-Datei. Hinweis:Wir empfehlen, sowohl das previewImage- als auch das previewLayout-Attribut anzugeben, damit Ihre App auf previewImage zurückgreifen kann, wenn das Gerät des Nutzers previewLayout nicht unterstützt. Weitere Informationen finden Sie unter Abwärtskompatibilität mit skalierbaren Widget-Vorschauen.
autoAdvanceViewId	Gibt die Ansichts-ID der Widget-Unteransicht an, die vom Host des Widgets automatisch vor- und zurückgescrollt wird.
widgetCategory	Gibt an, ob Ihr Widget auf dem Startbildschirm (home_screen), dem Sperrbildschirm (keyguard) oder auf beiden angezeigt werden kann. Ab Android 5.0 ist nur home_screen gültig.
widgetFeatures	Hier werden die vom Widget unterstützten Funktionen deklariert. Wenn Sie beispielsweise möchten, dass Ihr Widget die Standardkonfiguration verwendet, wenn ein Nutzer es hinzufügt, geben Sie sowohl das Flag configuration_optional als auch das Flag reconfigurable an. Dadurch wird verhindert, dass die Konfigurationsaktivität gestartet wird, nachdem ein Nutzer das Widget hinzugefügt hat. Der Nutzer kann das Widget danach neu konfigurieren.

Die AppWidgetProvider-Klasse zum Verarbeiten von Widget-Broadcasts verwenden

Die AppWidgetProvider-Klasse verarbeitet Widget-Broadcasts und aktualisiert das Widget als Reaktion auf Widget-Lebenszyklusereignisse. In den folgenden Abschnitten wird beschrieben, wie Sie AppWidgetProvider im Manifest deklarieren und dann implementieren.

Widget im Manifest deklarieren

Deklarieren Sie zuerst die AppWidgetProvider-Klasse in der AndroidManifest.xml-Datei Ihrer App, wie im folgenden Beispiel gezeigt:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

Das <receiver>-Element erfordert das Attribut android:name, das die vom Widget verwendete AppWidgetProvider angibt. Die Komponente muss nur exportiert werden, wenn ein separater Prozess an deine AppWidgetProvider übertragen werden muss. Das ist normalerweise nicht der Fall.

Das <intent-filter>-Element muss ein <action>-Element mit dem Attribut android:name enthalten. Mit diesem Attribut wird angegeben, dass die AppWidgetProvider die Übertragung von ACTION_APPWIDGET_UPDATE akzeptiert. Dies ist die einzige Übertragung, die Sie explizit deklarieren müssen. Die AppWidgetManager sendet alle anderen Widget-Broadcasts bei Bedarf automatisch an die AppWidgetProvider.

Das <meta-data>-Element gibt die AppWidgetProviderInfo-Ressource an und erfordert die folgenden Attribute:

• android:name: Gibt den Metadatennamen an. Verwenden Sie android.appwidget.provider, um die Daten als AppWidgetProviderInfo-Beschreibung zu identifizieren.
• android:resource: Gibt den Speicherort der AppWidgetProviderInfo-Ressource an.

AppWidgetProvider-Klasse implementieren

Die Klasse AppWidgetProvider erweitert BroadcastReceiver als praktische Klasse zum Verwalten von Widget-Broadcasts. Es empfängt nur die Ereignis-Broadcasts, die für das Widget relevant sind, z. B. wenn das Widget aktualisiert, gelöscht, aktiviert oder deaktiviert wird. Wenn diese Übertragungsereignisse auftreten, werden die folgenden AppWidgetProvider-Methoden aufgerufen:

onUpdate()

Diese Funktion wird aufgerufen, um das Widget in Intervallen zu aktualisieren, die durch das Attribut updatePeriodMillis in der AppWidgetProviderInfo definiert sind. Weitere Informationen finden Sie in der Tabelle mit zusätzlichen Widget-Attributen auf dieser Seite.

Diese Methode wird auch aufgerufen, wenn der Nutzer das Widget hinzufügt. So werden die erforderlichen Einstellungen vorgenommen, z. B. werden Ereignishandler für View-Objekte definiert oder Jobs gestartet, um Daten zu laden, die im Widget angezeigt werden sollen. Wenn Sie jedoch eine Konfigurationsaktivität ohne das configuration_optional-Flag deklarieren, wird diese Methode nicht aufgerufen, wenn der Nutzer das Widget hinzufügt, aber wird für die nachfolgenden Aktualisierungen aufgerufen. Die Konfigurationsaktivität ist dafür verantwortlich, das erste Update auszuführen, sobald die Konfiguration abgeschlossen ist. Weitere Informationen finden Sie unter Nutzer zum Konfigurieren von App-Widgets berechtigen.

Der wichtigste Rückruf ist onUpdate(). Weitere Informationen finden Sie auf dieser Seite unter Ereignisse mit der Klasse onUpdate() verarbeiten.

onAppWidgetOptionsChanged()

Diese Funktion wird aufgerufen, wenn das Widget zum ersten Mal platziert wird und jedes Mal, wenn es neu skaliert wird. Mit diesem Rückruf können Sie Inhalte basierend auf den Größenbereichen des Widgets anzeigen oder ausblenden. Rufen Sie getAppWidgetOptions() auf, um die Größenbereiche und ab Android 12 die Liste der möglichen Größen einer Widget-Instanz abzurufen. Sie erhalten dann eine Bundle mit den folgenden Informationen:

• OPTION_APPWIDGET_MIN_WIDTH: enthält die Untergrenze der Breite einer Widget-Instanz in dp-Einheiten.
• OPTION_APPWIDGET_MIN_HEIGHT: Enthält die untere Grenze der Höhe einer Widget-Instanz in dp-Einheiten.
• OPTION_APPWIDGET_MAX_WIDTH: enthält die Obergrenze für die Breite einer Widget-Instanz in dp-Einheiten.
• OPTION_APPWIDGET_MAX_HEIGHT: enthält die Obergrenze für die Höhe einer Widget-Instanz in dp-Einheiten.
• OPTION_APPWIDGET_SIZES: enthält eine Liste der möglichen Größen (List<SizeF>) in dp-Einheiten, die eine Widget-Instanz haben kann. Einführung in Android 12.

onDeleted(Context, int[])

Diese Funktion wird jedes Mal aufgerufen, wenn ein Widget vom Widget-Host gelöscht wird.

onEnabled(Context)

Diese Funktion wird aufgerufen, wenn eine Instanz des Widgets zum ersten Mal erstellt wird. Wenn der Nutzer beispielsweise zwei Instanzen Ihres Widgets hinzufügt, wird dieser Code nur beim ersten Mal aufgerufen. Wenn Sie eine neue Datenbank öffnen oder eine andere Einrichtung vornehmen müssen, die nur einmal für alle Widget-Instanzen erfolgen muss, ist dies der richtige Ort.

onDisabled(Context)

Diese Funktion wird aufgerufen, wenn die letzte Instanz Ihres Widgets vom Widget-Host gelöscht wird. Hier können Sie alle in onEnabled(Context) ausgeführten Arbeiten bereinigen, z. B. eine temporäre Datenbank löschen.

onReceive(Context, Intent)

Diese Methode wird für jede Übertragung und vor jeder der vorherigen Callback-Methoden aufgerufen. Normalerweise müssen Sie diese Methode nicht implementieren, da die Standardimplementierung von AppWidgetProvider alle Widget-Broadcasts filtert und die vorherigen Methoden entsprechend aufruft.

Sie müssen Ihre AppWidgetProvider-Klassenimplementierung mithilfe des <receiver>-Elements in der AndroidManifest als Broadcastempfänger deklarieren. Weitere Informationen finden Sie auf dieser Seite unter Widget im Manifest deklarieren.

Ereignisse mit der Klasse „onUpdate()“ verarbeiten

Der wichtigste AppWidgetProvider-Callback ist onUpdate(), da er aufgerufen wird, wenn jedem Widget ein Host hinzugefügt wird, es sei denn, Sie verwenden eine Konfigurationsaktivität ohne das Flag configuration_optional. Wenn Ihr Widget Nutzerinteraktionsereignisse akzeptiert, registrieren Sie die Event-Handler in diesem Rückruf. Wenn Ihr Widget keine temporären Dateien oder Datenbanken erstellt oder keine anderen Aufgaben ausführt, die beseitigt werden müssen, ist onUpdate() möglicherweise die einzige Rückrufmethode, die Sie definieren müssen.

Wenn Sie beispielsweise ein Widget mit einer Schaltfläche benötigen, die eine Aktivität startet, wenn darauf getippt wird, können Sie die folgende Implementierung von AppWidgetProvider verwenden:

Kotlin

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

Java

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

In diesem AppWidgetProvider wird nur die onUpdate()-Methode definiert, um ein PendingIntent zu erstellen, das ein Activity startet und mit setOnClickPendingIntent(int, PendingIntent) an die Schaltfläche des Widgets anhängt. Es enthält eine Schleife, die jeden Eintrag in appWidgetIds durchläuft. appWidgetIds ist ein Array von IDs, die jedes von diesem Anbieter erstellte Widget identifizieren. Wenn der Nutzer mehrere Instanzen des Widgets erstellt, werden sie alle gleichzeitig aktualisiert. Es wird jedoch nur ein updatePeriodMillis-Zeitplan für alle Instanzen des Widgets verwaltet. Wenn beispielsweise das Aktualisierungsintervall alle zwei Stunden festgelegt ist und eine zweite Instanz des Widgets eine Stunde nach der ersten hinzugefügt wird, werden beide Widgets im durch die erste Instanz festgelegten Zeitraum aktualisiert. Der zweite Aktualisierungszeitraum wird ignoriert. Beide werden alle zwei Stunden, nicht stündlich aktualisiert.

Hinweis: Da AppWidgetProvider eine Erweiterung von BroadcastReceiver ist, wird Ihr Prozess nicht garantiert fortgesetzt, nachdem die Rückgabe der Rückrufmethoden erfolgt ist. Informationen zum Übertragungslebenszyklus findest du unter BroadcastReceiver. Wenn die Einrichtung des Widgets mehrere Sekunden dauern kann, z. B. bei Webanfragen, und der Vorgang fortgesetzt werden soll, können Sie in der onUpdate()-Methode einen Task mit WorkManager starten. Innerhalb der Aufgabe können Sie eigene Updates am Widget vornehmen, ohne sich Gedanken darüber machen zu müssen, dass AppWidgetProvider aufgrund eines ANR-Fehlers (App antwortet nicht) geschlossen wird.

Weitere Informationen finden Sie in der Beispielklasse ExampleAppWidgetProvider.java.

Widget-Broadcast-Intents empfangen

AppWidgetProvider ist eine praktische Klasse. Wenn du die Widget-Broadcasts direkt erhalten möchtest, kannst du deine eigene BroadcastReceiver implementieren oder den onReceive(Context,Intent)-Callback überschreiben. Die folgenden Intents sind wichtig:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Widget-Layout erstellen

Sie müssen ein anfängliches Layout für Ihr Widget in XML definieren und es 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. Beachten Sie jedoch, dass Widget-Layouts auf RemoteViews basieren, das nicht alle Layout- oder Ansichts-Widgets unterstützt. Sie können keine benutzerdefinierten Ansichten oder Unterklassen der von RemoteViews unterstützten Ansichten verwenden.

RemoteViews unterstützt auch ViewStub, eine unsichtbare View mit einer Größe von null, mit der Sie Layoutressourcen bei der Laufzeit träge aufblähen können.

Unterstützung für zustandsorientiertes Verhalten

Android 12 unterstützt zustandsabhängiges Verhalten mit den folgenden vorhandenen Komponenten:

• CheckBox

• Switch

• RadioButton

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

Abbildung 3 Beispiel für zustandsorientiertes Verhalten.

Hinweis: Legen Sie den aktuellen Status immer explizit mit RemoteViews.setCompoundButtonChecked fest. Andernfalls kann es zu unerwarteten Ergebnissen kommen, wenn das Widget verschoben oder die Größe geändert wird.

Im folgenden Codebeispiel wird gezeigt, 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 eines für ältere Android-Versionen (Android 11 oder niedriger) im Standardordner res/layout.

Abgerundete Ecken implementieren

In Android 12 gibt es die folgenden Systemparameter, mit denen Sie den Radius der abgerundeten Ecken Ihres Widgets festlegen können:

• system_app_widget_background_radius: Der Eckradius des Widget-Hintergrunds, der nie größer als 28 dp ist.

• system_app_widget_inner_radius: Der Eckradius jeder Ansicht im Widget. Das ist genau 8 dp weniger als der Radius des Hintergrunds, damit eine gute Ausrichtung bei einem Abstand von 8 dp erzielt wird.

Das folgende Beispiel zeigt ein Widget, in dem system_app_widget_background_radius für die Ecke des Widgets und system_app_widget_inner_radius für Ansichten innerhalb des Widgets verwendet wird.

Abbildung 4: Abgerundete Ecken.

1 Ecke des Widgets.

2 Ecke einer Ansicht im Widget.

Wichtige Hinweise zu abgerundeten Ecken

• Launcher von Drittanbietern und Gerätehersteller können den Parameter system_app_widget_background_radius überschreiben, sodass er kleiner als 28 dp ist. Der Parameter system_app_widget_inner_radius ist immer 8 dp kleiner als der Wert von system_app_widget_background_radius.
• Wenn für Ihr Widget kein @android:id/background verwendet wird oder Sie keinen Hintergrund definieren, der den Inhalt basierend auf dem Umriss zuschneidet, und android:clipToOutline auf true festgelegt ist, erkennt der Launcher automatisch den Hintergrund und schneidet das Widget mit einem Rechteck mit abgerundeten Ecken von bis zu 16 dp zu. Weitere Informationen finden Sie unter Achten Sie darauf, dass Ihr Widget mit Android 12 kompatibel ist.

Für die Widget-Kompatibilität mit früheren Android-Versionen empfehlen wir, benutzerdefinierte Attribute zu definieren und sie mit einem benutzerdefinierten Design für Android 12 zu überschreiben, wie in den folgenden Beispiel-XML-Dateien gezeigt:

/values/attrs.xml

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

/values/styles.xml

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

/values-31/styles.xml

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

/drawable/my_widget_background.xml

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

/layout/my_widget_layout.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />