Nutzern erlauben, App-Widgets zu konfigurieren

App-Widgets können konfiguriert werden. Mit einem Uhr-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 ist ein Beispiel dafür, wie die Konfigurationsaktivität deklariert wird:

<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 des Paketbereichs darauf verweist.

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

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 muss in den Intent-Extras als EXTRA_APPWIDGET_ID gespeichert sein.
• 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. Setze das Aktivitätsergebnis auf RESULT_CANCELED.

   Wenn der Nutzer die Aktivität also vorzeitig beendet, 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. Wenn die Konfiguration abgeschlossen ist, rufen Sie eine Instanz von AppWidgetManager ab. Dazu rufen Sie getInstance(Context) auf:

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. Aktualisieren Sie das Widget mit einem RemoteViews-Layout. Rufen Sie dazu updateAppWidget(int,RemoteViews) auf:

   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. Erstellen Sie den Rückgabe-Intent, legen Sie ihn mit dem Aktivitätsergebnis fest und beenden Sie 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 ermöglichen, platzierte Widgets neu zu konfigurieren

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>