Nutzern erlauben, App-Widgets zu konfigurieren

App-Widgets können konfiguriert werden. Mit einem Uhren-Widget können Nutzer beispielsweise festlegen, welche Zeitzone angezeigt werden soll.

Wenn Sie Nutzern die Möglichkeit geben möchten, die Einstellungen Ihres Widgets zu konfigurieren, erstellen Sie eine Widgetkonfiguration Activity. Diese Aktivität wird vom App-Widget-Host automatisch gestartet, entweder beim Erstellen des Widgets oder später, je nach den von Ihnen angegebenen Konfigurationsoptionen.

Konfigurationsaktivität deklarieren

Deklarieren Sie die Konfigurationsaktivität in der Android-Manifestdatei als normale Aktivität. Der App-Widget-Host startet es mit der Aktion ACTION_APPWIDGET_CONFIGURE. Daher muss die Aktivität diesen Intent akzeptieren. Beispiel:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

Deklarieren Sie die Aktivität in der AppWidgetProviderInfo.xml-Datei mit dem Attribut android:configure. Weitere Informationen zum Deklarieren dieser Datei Hier ein Beispiel für die Deklaration der Konfigurationsaktivität:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

Die Aktivität wird mit einem voll qualifizierten Namespace deklariert, da der Launcher von außerhalb Ihres Paketbereichs darauf verweist.

Das ist alles, was Sie zum Starten einer Konfigurationsaktivität benötigen. Als Nächstes müssen Sie die eigentliche Aktivität implementieren.

Konfigurationsaktivität implementieren

Beachten Sie bei der Implementierung der Aktivität zwei wichtige Punkte:

• Der App-Widget-Host ruft die Konfigurationsaktivität auf und die Konfigurationsaktivität muss immer ein Ergebnis zurückgeben. Das Ergebnis muss die App-Widget-ID enthalten, die vom Intent übergeben wurde, der die Aktivität gestartet hat. Sie wird in den Intent-Extras als EXTRA_APPWIDGET_ID gespeichert.
• Das System sendet den Broadcast ACTION_APPWIDGET_UPDATE nicht, wenn eine Konfigurationsaktivität gestartet wird. Das bedeutet, dass die Methode onUpdate() nicht aufgerufen wird, wenn das Widget erstellt wird. Die Konfigurationsaktivität ist dafür verantwortlich, beim Erstellen des Widgets zum ersten Mal ein Update von AppWidgetManager anzufordern. onUpdate() wird jedoch bei nachfolgenden Aktualisierungen aufgerufen. Nur beim ersten Mal wird er übersprungen.

In den Code-Snippets im folgenden Abschnitt finden Sie ein Beispiel dafür, wie Sie ein Ergebnis aus der Konfiguration zurückgeben und das Widget aktualisieren.

Widget anhand der Konfigurationsaktivität aktualisieren

Wenn für ein Widget eine Konfigurationsaktivität verwendet wird, ist es Aufgabe der Aktivität, das Widget nach Abschluss der Konfiguration zu aktualisieren. Sie können direkt über die AppWidgetManager ein Update anfordern.

Hier eine Zusammenfassung der Schritte zum Aktualisieren des Widgets und Schließen der Konfigurationsaktivität:

1. Rufen Sie die App-Widget-ID aus dem Intent ab, über den die Aktivität gestartet wurde:

   Kotlin

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID

   Java

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }

2. Legen Sie das Aktivitätsergebnis auf RESULT_CANCELED fest.

   Wenn der Nutzer die Aktivität also vor dem Ende abbricht, benachrichtigt das System den App-Widget-Host, dass die Konfiguration abgebrochen wurde, und der Host fügt das Widget nicht hinzu:

   Kotlin

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)

   Java

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);

3. Konfigurieren Sie das Widget gemäß den Einstellungen des Nutzers.

4. Rufe nach Abschluss der Konfiguration getInstance(Context) auf, um eine Instanz von AppWidgetManager abzurufen:

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. Aktualisieren Sie das Widget mit einem RemoteViews-Layout, indem Sie updateAppWidget(int,RemoteViews) aufrufen:

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)

   Java

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);

6. Erstelle die Rückgabeabsicht, lege sie mit dem Aktivitätsergebnis fest und beende die Aktivität:

   Kotlin

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()

   Java

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();

Eine Beispielklasse finden Sie auf GitHub unter ListWidgetConfigureActivity.kt.

Widget-Konfigurationsoptionen

Standardmäßig startet der App-Widget-Host die Konfigurationsaktivität nur einmal, unmittelbar nachdem der Nutzer das Widget seinem Startbildschirm hinzugefügt hat. Sie können jedoch Optionen angeben, mit denen Nutzer vorhandene Widgets neu konfigurieren oder die Erstkonfiguration von Widgets überspringen können, indem Sie eine Standardkonfiguration für Widgets angeben.

Hinweis :Diese Optionen sind erst ab Android 12 (API-Level 31) verfügbar. Sie können sie für frühere Android-Versionen angeben, das System ignoriert sie jedoch und folgt dem Standardverhalten.

Nutzern das Neukonfigurieren platzierter Widgets ermöglichen

Wenn Nutzer vorhandene Widgets neu konfigurieren sollen, geben Sie das Flag reconfigurable im Attribut widgetFeatures von appwidget-provider an. Weitere Informationen finden Sie im Leitfaden zur Deklaration der AppWidgetProviderInfo.xml-Datei. Beispiel:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

Nutzer können ihr Widget neu konfigurieren, indem sie es gedrückt halten und auf die Schaltfläche Neu konfigurieren tippen, die in Abbildung 1 mit 1 gekennzeichnet ist.

Abbildung 1. Schaltfläche Widget neu konfigurieren

Hinweis: Das Flag reconfigurable wurde in Android 9 (API-Level 28) eingeführt, aber erst mit Android 12 allgemein unterstützt.

Standardkonfiguration des Widgets verwenden

Sie können die Nutzung des Widgets optimieren, indem Sie Nutzern die Möglichkeit geben, den ersten Konfigurationsschritt zu überspringen. Geben Sie dazu sowohl das Flag configuration_optional als auch das Flag reconfigurable im Feld widgetFeatures an. Dadurch wird verhindert, dass die Konfigurationsaktivität gestartet wird, nachdem ein Nutzer das Widget hinzugefügt hat. Wie bereits erwähnt, kann der Nutzer das Widget danach neu konfigurieren. Ein Uhren-Widget kann beispielsweise die Erstkonfiguration umgehen und standardmäßig die Zeitzone des Geräts anzeigen.

Hier ein Beispiel dafür, wie Sie Ihre Konfigurationsaktivität als neu konfigurierbar und optional kennzeichnen:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>