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 ist automatisch vom App-Widget-Host gestartet, entweder beim Erstellen des Widgets oder später, je nach den Konfigurationsoptionen, die Sie angeben.

Konfigurationsaktivität deklarieren

Konfigurationsaktivität im Android-Manifest als normale Aktivität deklarieren -Datei. Der Host des App-Widgets startet es mit der ACTION_APPWIDGET_CONFIGURE Aktion, sodass die Aktivität diesen Intent akzeptieren muss. 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 Datei AppWidgetProviderInfo.xml mit dem android:configure-Attribut. Weitere Informationen zu deklarieren dieser Datei. Hier ist ein Beispiel fü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 außerhalb des Paketbereichs darauf verweist.

Das ist alles, was Sie brauchen, um eine Konfigurationsaktivität zu starten. Als Nächstes müssen Sie die eigentliche Aktivität implementieren.

Konfigurationsaktivität implementieren

Es gibt zwei wichtige Punkte, die Sie bei der Implementierung der Aktivität beachten sollten:

• 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. Sie können jedoch onUpdate() wird für nachfolgende Updates aufgerufen. Es wird nur der beim ersten Mal.

Die Code-Snippets im folgenden Abschnitt zeigen ein Beispiel für die Rückgabe einer aus der Konfiguration und aktualisieren das Widget.

Widget anhand der Konfigurationsaktivität aktualisieren

Wenn ein Widget eine Konfigurationsaktivität verwendet, Die Aktivität zum Aktualisieren des Widgets nach Abschluss der Konfiguration. Sie können Folgendes tun: indem Sie eine Aktualisierung direkt im AppWidgetManager

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

1. Rufen Sie die App-Widget-ID vom Intent ab, der die Aktivität gestartet hat:

   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 Nutzende die Aktivität abbrechen, bevor sie am Ende angelangt sind, App-Widget-Host benachrichtigt, 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 durch Aufrufen von updateAppWidget(int,RemoteViews):

   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 die Aktivität beenden:

   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.

Konfigurationsoptionen für Widgets

Standardmäßig startet der App-Widget-Host die Konfigurationsaktivität nur einmal. nachdem der Nutzer das Widget seinem Startbildschirm hinzugefügt hat. Sie haben jedoch kann Optionen angeben, mit denen Sie Nutzern die Neukonfiguration bestehender Widgets oder die anfängliche Widget-Konfiguration überspringen, indem Sie eine Standard-Widget-Konfiguration bereitstellen.

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 in der Anleitung zur Deklaration der AppWidgetProviderInfo.xml-Datei für weitere Informationen Informationen. 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. 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 wird standardmäßig die Zeitzone des Geräts angezeigt.

Hier ist ein Beispiel dafür, wie Sie Ihre Konfigurationsaktivität rekonfigurierbar und optional:

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