Einfaches Widget erstellen

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

</ph>

In diesem Dokument wird beschrieben, wie Sie ein Widget mithilfe eines Widget-Anbieters veröffentlichen. Für Informationen zum Erstellen eines eigenen AppWidgetHost für finden Sie unter Widgethost erstellen.

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

Widget-Komponenten

Zum Erstellen eines Widgets benötigen Sie die folgenden Grundkomponenten:

Objekt AppWidgetProviderInfo

Beschreibt die Metadaten für ein Widget, z. B. das Layout, das Update Häufigkeit und AppWidgetProvider-Klasse. AppWidgetProviderInfo ist in XML definiert, wie folgt: wie in diesem Dokument beschrieben.

AppWidgetProvider Kurs

Definiert die grundlegenden Methoden, die eine programmatischen Schnittstelle mit dem Widget. Sie erhalten Broadcasts, wenn das Widget aktualisiert wird, aktiviert, deaktiviert oder gelöscht. Sie deklarieren AppWidgetProvider in der Manifest-Datei und implementieren Sie es dann wie folgt: wie in diesem Dokument beschrieben.

Layout ansehen

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

Abbildung 2 zeigt, wie sich diese Komponenten in die gesamte Verarbeitung des App-Widgets einfügen. Ablauf.

</ph>

Wenn für Ihr Widget eine Nutzerkonfiguration erforderlich ist, implementieren Sie die Konfiguration des App-Widgets. Aktivitäten. 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 Standardeinstellung für Konfiguration und lassen Sie die Nutzer das Widget später neu konfigurieren. Weitere Informationen finden Sie unter Verwenden der Standardkonfiguration des Widgets und Aktivieren Nutzer können platzierte Widgets neu konfigurieren .
• Ab Android 11 (API-Level 30) wird diese Aktivität jedes Mal gestartet wenn Nutzende das Widget zu ihrem Startbildschirm hinzufügen.

Wir empfehlen auch die folgenden Verbesserungen: flexible Widget-Layouts, Verschiedene Verbesserungen, erweiterte Widgets, Sammlungs-Widgets und Widgets erstellen Host.

AppWidgetProviderInfo-XML deklarieren

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

Dies wird im folgenden Beispiel gezeigt:

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

Größenattribute für das Widget

Der Standardstartbildschirm positioniert Widgets in seinem Fenster basierend auf einem Zellenraster. mit einer definierten Höhe und Breite. Auf den meisten Startbildschirmen Größen, die ganzzahlige Vielfache der Rasterzellen sind, z. B. zwei Zellen horizontal durch drei vertikal angeordnete Zellen.

Mit den Widget-Größenattributen können Sie eine Standardgröße für Ihr Widget festlegen eine Unter- und Obergrenze für die Größe des Widgets festlegen. In diesem Zusammenhang Die Standardgröße eines Widgets ist die Größe, die das Widget annimmt, wenn es die dem Startbildschirm hinzugefügt wurden.

In der folgenden Tabelle werden die <appwidget-provider>-Attribute für bis zur Widget-Größe:

Beispiel

Um zu veranschaulichen, wie sich die Attribute in der vorstehenden Tabelle auf die Widget-Größe auswirken, gehen wir von 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:

Die Attribute targetCellWidth und targetCellHeight als Standard verwenden die Größe des Widgets.

Das Widget ist standardmäßig 2 x 2 groß. Das Widget kann auf 2 x 1 oder bis zu 4 x 3.

Android 11 und niedriger:

Verwenden Sie die Attribute minWidth und minHeight, um die Standardgröße der um das Widget zu öffnen.

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

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

Das Widget ist standardmäßig 3 x 2 groß. Das Widget kann auf 2 x 1 oder bis zum Vollbildmodus.

Zusätzliche Widget-Attribute

In der folgenden Tabelle werden die <appwidget-provider>-Attribute für anderen Qualitäten als der Widget-Größe angepasst werden.

Widget-Broadcasts mithilfe der AppWidgetProvider-Klasse verarbeiten

Die Klasse AppWidgetProvider verarbeitet Widget-Broadcasts und aktualisiert das Widget als Reaktion auf Widget-Lebenszyklus-Ereignisse. In den folgenden Abschnitten wird beschrieben, wie Sie Deklariere AppWidgetProvider im Manifest und implementiere es dann.

Widget im Manifest deklarieren

Deklariere zuerst die Klasse AppWidgetProvider in der AndroidManifest.xml deiner 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>

Für das <receiver>-Element ist das android:name-Attribut erforderlich. Dieses gibt an, Der vom Widget verwendete AppWidgetProvider. Die Komponente darf nicht exportiert werden es sei denn, ein separater Prozess muss eine Nachricht an Ihre AppWidgetProvider senden, die ist normalerweise nicht der Fall.

Das <intent-filter>-Element muss ein <action>-Element mit dem android:name. Dieses Attribut gibt an, dass das AppWidgetProvider akzeptiert die ACTION_APPWIDGET_UPDATE Nachricht an alle. Dies ist die einzige Übertragung, die du explizit erklären musst. Die AppWidgetManager sendet automatisch alle anderen Widget-Broadcasts an AppWidgetProvider als notwendig ist.

Das Element <meta-data> gibt die Ressource AppWidgetProviderInfo und benötigt folgende Attribute:

• android:name: gibt den Metadatennamen an. Verwenden Sie android.appwidget.provider, um die Daten als die AppWidgetProviderInfo-Deskriptor.
• android:resource: gibt die Ressource AppWidgetProviderInfo an Standort.

AppWidgetProvider-Klasse implementieren

Die AppWidgetProvider-Klasse umfasst BroadcastReceiver als Convenience-Klasse für die Verarbeitung von Widget-Broadcasts. Er empfängt nur das Ereignis Broadcasts, die für das Widget relevant sind, z. B. wenn das Widget aktualisiert wird, gelöscht, aktiviert und deaktiviert. Bei diesen Broadcast-Ereignissen geschieht Folgendes: AppWidgetProvider-Methoden werden aufgerufen:

onUpdate()

Wird aufgerufen, um das Widget in den durch das updatePeriodMillis-Attribut in AppWidgetProviderInfo. Tabelle ansehen weitere Widget-Attribute auf dieser Seite für erhalten Sie weitere Informationen.

Diese Methode wird auch aufgerufen, wenn der Nutzer das Widget hinzufügt. wie die Definition von Event-Handlern View-Objekte oder Startjobs zum Laden von Daten im Widget angezeigt wird. Wenn Sie jedoch eine Konfigurationsaktivität ohne configuration_optional haben, wird diese Methode nicht aufgerufen, wenn der Nutzer fügt das Widget hinzu, wird jedoch für die nachfolgenden Updates aufgerufen. Es handelt sich um die der Konfigurationsaktivität für die Ausführung des ersten Updates, wenn die Konfiguration abgeschlossen ist. Weitere Informationen finden Sie unter Nutzern erlauben, App-Widgets zu konfigurieren.

Der wichtigste Callback ist onUpdate(). Weitere Informationen finden Sie unter Ereignisse mit dem onUpdate() auf dieser Seite.

onAppWidgetOptionsChanged()

Dieser wird aufgerufen, wenn das Widget zum ersten Mal platziert wird, und jedes Mal, wenn das Widget in der Größe angepasst. Verwenden Sie diesen Callback, um Inhalte basierend auf der Größe des Widgets ein- oder auszublenden Bereiche. Sehen Sie sich die Größenbereiche an. Ab Android 12 die Liste möglicher Größen einer Widget-Instanz – durch Aufrufen getAppWidgetOptions(), gibt ein Bundle-Objekt zurück, das den Folgendes:

• OPTION_APPWIDGET_MIN_WIDTH: enthält die Untergrenze für die 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 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 die Liste der möglichen Größen (List<SizeF>) in dp-Einheiten, die ein Widget-Instanz ausführen kann. Mit Android 12 eingeführt.

onDeleted(Context, int[])

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

onEnabled(Context)

Dieses wird aufgerufen, wenn eine Instanz des Widgets zum ersten Mal erstellt wird. Wenn der Nutzer beispielsweise zwei Instanzen deines Widgets hinzufügt, wird dies nur als beim ersten Mal. Wenn Sie eine neue Datenbank öffnen oder eine andere Einrichtung durchführen müssen, nur einmal für alle Widget-Instanzen erfolgen muss, Tu es.

onDisabled(Context)

Dieser wird aufgerufen, wenn die letzte Instanz Ihres Widgets aus dem Widget-Host. Hier bereinigen Sie alle in onEnabled(Context) erledigten Aufgaben. wie das Löschen einer temporären Datenbank.

onReceive(Context, Intent)

Dies wird bei jeder Übertragung und vor jedem der vorhergehenden Callbacks aufgerufen. . Normalerweise müssen Sie diese Methode nicht implementieren, Die Implementierung von AppWidgetProvider filtert alle Widget-Broadcasts und ruft die Methode vorherigen Methoden.

Sie müssen die Implementierung der Klasse AppWidgetProvider als Übertragung deklarieren -Empfänger mit dem <receiver>-Element in AndroidManifest. Weitere Informationen finden Sie unter Deklarieren eines im Manifest auf dieser Seite.

Ereignisse mit der onUpdate()-Klasse verarbeiten

Der wichtigste AppWidgetProvider-Callback ist onUpdate(), weil er aufgerufen, wenn jedes Widget zu einem Host hinzugefügt wird, es sei denn, Sie verwenden eine Konfiguration Aktivität ohne das Flag configuration_optional. Wenn Ihr Widget Nutzerinteraktionsereignisse und anschließend die Ereignis-Handler in diesem Callback registrieren. Wenn Ihr Widget erstellt keine temporären Dateien oder Datenbanken und führt keine anderen Aufgaben aus die eine Bereinigung erfordert, dann ist onUpdate() möglicherweise die einzige Callback-Methode, die du definieren müssen.

Wenn Sie z. B. ein Widget mit einer Schaltfläche benötigen, die eine Aktivität startet, angetippt haben, können Sie 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);
        }
    }
}

Dieses AppWidgetProvider definiert nur die onUpdate()-Methode und verwendet sie, um eine PendingIntent erstellen, die ein neues ein Activity-Element und fügt es mit dem Widget mit setOnClickPendingIntent(int, PendingIntent). Sie enthält eine Schleife, die jeden Eintrag durchläuft. in appWidgetIds ein Array mit IDs zur Identifizierung der einzelnen Widgets, die von diesem Anbieter. Wenn der Nutzer mehr als eine Instanz des Widgets erstellt, dann: werden alle gleichzeitig aktualisiert. Allerdings gibt es nur einen updatePeriodMillis-Zeitplan wird für alle Instanzen des Widgets verwaltet. Wenn der Aktualisierungszeitplan beispielsweise alle zwei Stunden festgelegt ist, und eine zweite Instanz des Widgets wird hinzugefügt. eine Stunde nach der ersten angezeigt, dann werden beide gemäß dem der erste und der zweite Aktualisierungszeitraum ignoriert. Beide werden alle zwei Wochen aktualisiert. nicht jede Stunde.

Weitere Informationen finden Sie in der ExampleAppWidgetProvider.java Beispielklasse.

Widget-Übertragungs-Intents empfangen

AppWidgetProvider ist eine Convenience-Klasse. Wenn du das Widget erhalten möchtest sendet, können Sie Ihre eigene BroadcastReceiver implementieren oder die onReceive(Context,Intent)-Rückruf. Die Intents, auf die Sie sich konzentrieren müssen, Folgendes:

• 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 im Verzeichnis res/layout/ des Projekts. Weitere Informationen finden Sie unter Design .

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

RemoteViews unterstützt auch ViewStub, Dies ist ein unsichtbares View-Element mit Nullgröße, mit dem Sie das Layout mit Lazy-Inflation ausführen können. Ressourcen während der Laufzeit.

Unterstützung für zustandsorientiertes Verhalten

Android 12 unterstützt zustandsorientiertes Verhalten mithilfe von vorhandenen Komponenten:

• CheckBox

• Switch

• RadioButton

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

</ph>

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 res/layout-v31 höher und der andere Targeting-Wert auf Android 11 oder niedriger im Standardordner res/layout.

Abgerundete Ecken implementieren

Mit Android 12 werden die folgenden Systemparameter eingeführt, um die Radien der abgerundeten Ecken des Widgets:

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

• system_app_widget_inner_radius: den Eckenradius jeder Ansicht im Widget. Das sind genau 8 dp. kleiner als der Hintergrundradius, um bei Verwendung von 8 dp eine gute Ausrichtung zu erreichen. Abstand.

Das folgende Beispiel zeigt ein Widget, system_app_widget_background_radius für die Ecke des Widgets und system_app_widget_inner_radius für Ansichten im Widget.

</ph>

1 Ecke des Widgets.

2 Ecke einer Ansicht im Widget.

Wichtige Hinweise zu abgerundeten Ecken

• Launcher von Drittanbietern und Gerätehersteller können system_app_widget_background_radius-Parameter muss kleiner als 28 dp sein. Der Parameter system_app_widget_inner_radius ist immer 8 dp kleiner als Wert von system_app_widget_background_radius
• Wenn für dein Widget weder „@android:id/background“ verwendet noch ein Hintergrund festgelegt wird der seine Inhalte basierend auf dem Umriss zuschneidet – mit android:clipToOutline true festgelegt, erkennt der Launcher automatisch den Hintergrund und das Widget mithilfe eines Rechtecks mit abgerundeten Ecken von bis zu 16 dp zuschneidet. Weitere Informationen finden Sie unter Überprüfen, ob Ihr Widget kompatibel ist mit Android 12

Für die Widget-Kompatibilität mit früheren Android-Versionen empfehlen wir, Definition benutzerdefinierter Attribute und Verwendung eines benutzerdefinierten Designs, um sie für Android 12, 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" />