Nutzern erlauben, App-Widgets zu konfigurieren

Gestalte dein Widget so, dass Nutzer bestimmte Merkmale konfigurieren können. In 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 automatisch vom App-Widget-Host gestartet, entweder beim Erstellen des Widgets oder später, je nach den von Ihnen angegebenen Konfigurationsoptionen.

Konfigurationsaktivität deklarieren

Deklarieren Sie die Konfigurationsaktivität als normale Aktivität in der Android-Manifestdatei. Der App-Widget-Host startet das Widget mit der Aktion ACTION_APPWIDGET_CONFIGURE. Die Aktivität muss diesen Intent also 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 Datei AppWidgetProviderInfo.xml mit dem Attribut android:configure. Weitere Informationen zum Deklarieren dieser Datei Hier sehen Sie 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 müssen Sie die eigentliche Aktivität implementieren.

Konfigurationsaktivität implementieren

Bei der Implementierung der Aktivität sind zwei wichtige Punkte zu beachten:

• 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, mit dem die Aktivität gestartet wurde. 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 Ihre Widget-Updates beim Erstellen des Widgets nicht aufgerufen werden. Die Konfigurationsaktivität ist dafür verantwortlich, beim ersten Erstellen des Widgets ein Update von GlanceAppWidget anzufordern. Updates werden jedoch für nachfolgende Zyklen automatisch ausgelöst.

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

Widget über die Konfigurationsaktivität aktualisieren

Wenn ein Widget eine Konfigurationsaktivität verwendet, ist es die Aufgabe der Aktivität, das Widget zu aktualisieren, wenn die Konfiguration abgeschlossen ist. Dazu können Sie ein manuelles Update direkt über die GlanceAppWidget-Instanz auslösen.

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

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

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

2. Setzen Sie das Aktivitätsergebnis auf RESULT_CANCELED.

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

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

3. Konfigurieren Sie das Widget entsprechend den Einstellungen des Nutzers, z. B. indem Sie die Auswahl in einem persistenten DataStore oder einer lokalen Datenbank speichern.

4. Rufen Sie nach Abschluss der Konfiguration die GlanceId für die Plattform-Widget-ID ab:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Aktualisieren Sie den Widget-Inhalt, indem Sie die update-Funktion für Ihre GlanceAppWidget-Instanz aufrufen:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Erstellen Sie die Rückgabeabsicht, legen Sie sie mit dem Aktivitätsergebnis fest und schließen Sie die Aktivität ab:

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

Optionen für die Widget-Konfiguration

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 der Nutzer vorhandene Widgets neu konfigurieren oder die anfängliche Widget-Konfiguration überspringen kann, indem Sie eine Standard-Widget-Konfiguration bereitstellen.

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. 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 (siehe Abbildung 1, Nummer 1).

Standardkonfiguration des Widgets verwenden

Sie können ein nahtloseres Widget-Erlebnis bieten, indem Sie Nutzern ermöglichen, den ersten Konfigurationsschritt zu überspringen. Geben Sie dazu im Feld widgetFeatures sowohl das Flag configuration_optional als auch das Flag reconfigurable an. Dadurch wird das Starten der Konfigurationsaktivität umgangen, nachdem ein Nutzer das Widget hinzugefügt hat. Wie bereits erwähnt, kann der Nutzer das Widget später neu konfigurieren. Ein Uhr-Widget kann beispielsweise die Erstkonfiguration umgehen und standardmäßig die Zeitzone des Geräts anzeigen.

Hier sehen Sie ein Beispiel dafür, wie Sie Ihre Konfigurationsaktivität als sowohl rekonfigurierbar als auch optional kennzeichnen:

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