Einfaches Widget erstellen

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

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

Informationen zum Entwerfen des Widgets finden Sie unter App-Widgets – Übersicht.

Widget-Komponenten

Sie benötigen die folgenden grundlegenden Komponenten, um ein Widget zu erstellen:

AppWidgetProviderInfo-Objekt

Beschreibt die Metadaten für ein Widget, z. B. Layout, Aktualisierungshäufigkeit und Klasse AppWidgetProvider. AppWidgetProviderInfo ist in XML definiert, wie in diesem Dokument beschrieben.

Klasse AppWidgetProvider

Definiert die grundlegenden Methoden, mit denen Sie das Widget programmatisch bedienen können. Sie erhalten Broadcasts, wenn das Widget aktualisiert, aktiviert, deaktiviert oder gelöscht wird. Sie deklarieren AppWidgetProvider im Manifest und implementieren den Code dann wie in diesem Dokument beschrieben.

Layout anzeigen

Definiert das anfängliche Layout für das Widget. Das Layout wird, wie in diesem Dokument beschrieben, in XML definiert.

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

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

• Ab Android 12 (API-Level 31) kannst du 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 dürfen platzierte Widgets neu konfigurieren.
• Unter Android 11 (API-Level 30) oder niedriger wird diese Aktivität jedes Mal gestartet, wenn der Nutzer das Widget zu seinem Startbildschirm hinzufügt.

Außerdem empfehlen wir die folgenden Verbesserungen: Flexible Widget-Layouts, verschiedene Verbesserungen, erweiterte Widgets, Sammlungs-Widgets und Widget-Host erstellen.

AppWidgetProviderInfo-XML deklarieren

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

Dies wird im folgenden Beispiel veranschaulicht:

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

Widget-Größenattribute

Auf dem Standardstartbildschirm werden Widgets im Fenster basierend auf einem Raster von Zellen positioniert, die eine definierte Höhe und Breite haben. Auf den meisten Startbildschirmen können Widgets nur Größen annehmen, die ein ganzzahliges Vielfaches der Rasterzellen sind, z. B. zwei Zellen horizontal mal drei Zellen vertikal.

Mit den Widget-Größenattributen können Sie eine Standardgröße für das Widget sowie Unter- und Obergrenzen für die Größe des Widgets angeben. In diesem Kontext ist die Standardgröße eines Widgets die Größe, die das Widget annimmt, wenn es zum ersten Mal dem Startbildschirm hinzugefügt wird.

In der folgenden Tabelle werden die <appwidget-provider>-Attribute für die Widgetgröße beschrieben:

Beispiel

Um zu veranschaulichen, wie sich die Attribute in der vorherigen Tabelle auf die Größe von Widgets auswirken, gehen Sie von den folgenden Spezifikationen aus:

• Eine Zelle im Raster 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 Größe des Widgets ist standardmäßig 2 x 2. Die Größe des Widgets kann auf 2 x 1 oder bis zu 4 x 3 reduziert 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

Die Größe des Widgets ist standardmäßig 3 x 2. Die Größe des Widgets kann auf 2 x 1 oder bis auf Vollbild verkleinert werden.

Zusätzliche Widget-Attribute

In der folgenden Tabelle werden die <appwidget-provider>-Attribute für andere Eigenschaften als die Widget-Größe beschrieben.

AppWidgetProvider-Klasse zur Verarbeitung von Widget-Broadcasts verwenden

Die Klasse AppWidgetProvider verarbeitet Widget-Broadcasts und aktualisiert das Widget als Reaktion auf Widget-Lebenszyklusereignisse. In den folgenden Abschnitten wird beschrieben, wie AppWidgetProvider im Manifest deklariert und anschließend implementiert wird.

Widget im Manifest deklarieren

Deklarieren Sie zuerst die Klasse AppWidgetProvider in der Datei AndroidManifest.xml Ihrer Anwendung, 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>

Für das <receiver>-Element ist das Attribut android:name erforderlich, das die vom Widget verwendete AppWidgetProvider angibt. Die Komponente darf nur exportiert werden, wenn ein separater Prozess an Ihre AppWidgetProvider gesendet wird, was in der Regel nicht der Fall ist.

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

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

• android:name: Gibt den Namen der Metadaten an. Verwenden Sie android.appwidget.provider, um die Daten als AppWidgetProviderInfo-Deskriptor anzugeben.
• android:resource: gibt den Ressourcenstandort AppWidgetProviderInfo an.

AppWidgetProvider-Klasse implementieren

Die Klasse AppWidgetProvider erweitert BroadcastReceiver als praktische Klasse zur Verarbeitung von Widget-Broadcasts. Sie empfängt nur die für das Widget relevanten Ereignissendungen, z. B. wenn das Widget aktualisiert, gelöscht, aktiviert und deaktiviert wird. Wenn diese Übertragungsereignisse auftreten, werden die folgenden AppWidgetProvider-Methoden aufgerufen:

onUpdate()

Wird aufgerufen, um das Widget in Intervallen zu aktualisieren, die durch das Attribut updatePeriodMillis im AppWidgetProviderInfo definiert werden. Weitere Informationen finden Sie auf dieser Seite in der Tabelle mit den zusätzlichen Widget-Attributen.

Diese Methode wird auch aufgerufen, wenn der Nutzer das Widget hinzufügt. Dadurch wird die grundlegende Einrichtung durchgeführt, z. B. das Definieren von Event-Handlern für View-Objekte oder das Starten von Jobs zum Laden von Daten, die im Widget angezeigt werden sollen. Deklarieren Sie jedoch eine Konfigurationsaktivität ohne das Flag configuration_optional, wird diese Methode beim Hinzufügen des Widgets nicht aufgerufen, sondern für die nachfolgenden Aktualisierungen . Es liegt in der Verantwortung der Konfigurationsaktivität, die erste Aktualisierung nach Abschluss der Konfiguration durchzuführen. Weitere Informationen finden Sie unter Nutzern erlauben, App-Widgets zu konfigurieren.

Der wichtigste Callback ist onUpdate(). Weitere Informationen findest du auf dieser Seite unter Ereignisse mit der Klasse onUpdate() verarbeiten.

onAppWidgetOptionsChanged()

Sie wird aufgerufen, wenn das Widget zum ersten Mal platziert wird und jedes Mal, wenn die Größe des Widgets geändert wird. Mit diesem Callback können Sie Inhalte basierend auf den Größenbereichen des Widgets ein- oder ausblenden. Die Größenbereiche und ab Android 12 die Liste möglicher Größen für eine Widget-Instanz können Sie abrufen. Dazu rufen Sie getAppWidgetOptions() auf. Dadurch wird ein Bundle-Objekt zurückgegeben, das Folgendes enthält:

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

onDeleted(Context, int[])

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

onEnabled(Context)

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

onDisabled(Context)

Sie wird aufgerufen, wenn die letzte Instanz des Widgets vom Widget-Host gelöscht wird. Hier bereinigen Sie alle in onEnabled(Context) ausgeführten Arbeiten, z. B. das Löschen einer temporären Datenbank.

onReceive(Context, Intent)

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

Sie müssen die Implementierung der AppWidgetProvider-Klasse als Übertragungsempfänger mit dem Element <receiver> in der Datei AndroidManifest 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 jedes Widget einem Host hinzugefügt wird, sofern Sie keine Konfigurationsaktivität ohne das Flag configuration_optional verwenden. Wenn Ihr Widget Nutzerinteraktionsereignisse akzeptiert, registrieren Sie die Event-Handler in diesem Callback. Wenn Ihr Widget keine temporären Dateien oder Datenbanken erstellt und keine anderen Arbeiten ausführt, die eine Bereinigung erfordern, ist onUpdate() möglicherweise die einzige Callback-Methode, die Sie definieren müssen.

Wenn du beispielsweise ein Widget mit einer Schaltfläche haben möchtest, die beim Antippen eine Aktivität startet, kannst du die folgende Implementierung von AppWidgetProvider verwenden:

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

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

Diese AppWidgetProvider definiert nur die Methode onUpdate() und verwendet sie zum Erstellen eines PendingIntent, das einen Activity startet und mit setOnClickPendingIntent(int, PendingIntent) an die Schaltfläche des Widgets anhängt. Sie enthält eine Schleife, die jeden Eintrag in appWidgetIds durchläuft. Dabei handelt es sich um ein Array von IDs, mit denen jedes von diesem Anbieter erstellte Widget identifiziert wird. Wenn der Nutzer mehr als eine Instanz des Widgets erstellt, werden alle gleichzeitig aktualisiert. Es wird jedoch nur ein updatePeriodMillis-Zeitplan für alle Instanzen des Widgets verwaltet. Wenn der Aktualisierungszeitplan beispielsweise alle zwei Stunden festgelegt ist und eine zweite Instanz des Widgets eine Stunde nach der ersten hinzugefügt wird, werden beide in dem von der ersten Instanz festgelegten Zeitraum aktualisiert und der zweite Aktualisierungszeitraum wird ignoriert. Sie werden alle zwei Stunden aktualisiert, nicht stündlich.

Weitere Informationen finden Sie in der Beispielklasse ExampleAppWidgetProvider.java.

Widget-Broadcast-Intents empfangen

AppWidgetProvider ist eine Convenience-Klasse. Wenn du die Widget-Übertragungen direkt empfangen möchtest, kannst du deinen eigenen 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

Definieren Sie für das Widget ein anfängliches Layout in XML und speichern Sie es im Verzeichnis res/layout/ des Projekts. Weitere Informationen finden Sie in den Designrichtlinien.

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

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

Unterstützung für zustandsorientiertes Verhalten

Android 12 unterstützt jetzt zustandsorientiertes Verhalten mithilfe der folgenden vorhandenen Komponenten:

• CheckBox

• Switch

• RadioButton

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

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

// 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 vorheriges Android 11 oder niedriger im standardmäßigen res/layout-Ordner.

Abgerundete Ecken verwenden

In Android 12 werden die folgenden Systemparameter eingeführt, um die Radien der abgerundeten Ecken Ihres Widgets festzulegen:

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

• system_app_widget_inner_radius: der Eckenradius einer beliebigen Ansicht im Widget. Das ist genau 8 dp kleiner als der Hintergrundradius, um bei Verwendung eines Abstands von 8 dp eine optimale Ausrichtung zu erzielen.

Das folgende Beispiel zeigt ein Widget, bei 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.

1 Ecke des Widgets.

2 Ecke einer Ansicht innerhalb des Widgets.

Wichtige Hinweise zu abgerundeten Ecken

• Launcher von Drittanbietern und Gerätehersteller können den Parameter system_app_widget_background_radius so überschreiben, dass 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 dein Widget @android:id/background nicht verwendet oder einen Hintergrund definiert, der den Inhalt anhand des Umrisses zuschneidet, wobei android:clipToOutline auf true gesetzt ist, erkennt der Launcher automatisch den Hintergrund und schneidet das Widget mithilfe eines Rechtecks mit abgerundeten Ecken von bis zu 16 dp zu. Weitere Informationen finden Sie unter Kompatibilität mit Android 12 sicherstellen.

Damit Widgets mit früheren Android-Versionen kompatibel sind, empfehlen wir, benutzerdefinierte Attribute zu definieren und sie für Android 12 mit einem benutzerdefinierten Design zu überschreiben, wie in den folgenden Beispiel-XML-Dateien gezeigt:

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

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

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

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

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