Nutzern erlauben, App-Widgets zu konfigurieren

Gestalten Sie Ihr Widget so, dass Nutzer bestimmte Merkmale konfigurieren können. Bei einem Uhr-Widget können Nutzer beispielsweise die anzuzeigende Zeitzone konfigurieren.

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

Konfigurations-Activity deklarieren

Deklarieren Sie die Konfigurations-Activity als normale Activity in der Android-Manifestdatei. Der App-Widget-Host startet sie mit der ACTION_APPWIDGET_CONFIGURE Aktion. Die Activity muss daher diesen Intent akzeptieren. Beispiel:

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

Deklarieren Sie die Activity in der Datei AppWidgetProviderInfo.xml mit dem Attribut android:configure. Weitere Informationen zum Deklarieren dieser Datei. Beispiel für die Deklaration der Konfigurations-Activity:

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

Die Activity 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 Konfigurations-Activity benötigen. Als Nächstes müssen Sie die eigentliche Activity implementieren.

Konfigurations-Activity implementieren

Bei der Implementierung der Activity sind zwei wichtige Punkte zu beachten:

• Der App-Widget-Host ruft die Konfigurations-Activity auf und die Konfigurations-Activity muss immer ein Ergebnis zurückgeben. Das Ergebnis muss die App-Widget ID enthalten, die vom Intent übergeben wurde, mit dem die Activity gestartet wurde. Sie wird in den Intent Extras als EXTRA_APPWIDGET_ID gespeichert.
  • Das System sendet die ACTION_APPWIDGET_UPDATE Broadcast-Nachricht nicht, wenn eine Konfigurations-Activity gestartet wird. Das bedeutet, dass Ihre Widget-Updates beim Erstellen des Widgets nicht aufgerufen werden. Die Konfigurations-Activity ist dafür verantwortlich, beim ersten Erstellen des Widgets ein Update von GlanceAppWidget anzufordern. Bei nachfolgenden Zyklen werden Updates jedoch 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 Konfigurations-Activity aktualisieren

Wenn ein Widget eine Konfigurations-Activity verwendet, ist die Activity dafür verantwortlich, das Widget nach Abschluss der Konfiguration zu aktualisieren. Sie können dies tun, indem Sie ein manuelles Update direkt über die GlanceAppWidget-Instanz auslösen.

Hier eine Zusammenfassung der Schritte zum ordnungsgemäßen Aktualisieren des Widgets und Schließen der Konfigurations-Activity:

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

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

2. Legen Sie das Ergebnis der Activity auf RESULT_CANCELED fest.

   Wenn der Nutzer die Activity beendet, bevor er das Ende erreicht, 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 nach den Vorlieben des Nutzers, z. B. indem Sie die Auswahl in einem persistenten Datenspeicher oder einer lokalen Datenbank speichern.

4. Rufen Sie nach Abschluss der Konfiguration die GlanceId ab, die der Plattform-Widget-ID entspricht:

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

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

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

6. Erstellen Sie den Rückgabe-Intent, legen Sie ihn mit dem Ergebnis der Activity fest und beenden Sie die Activity:

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

Widgetkonfigurationsoptionen

Standardmäßig startet der App-Widget-Host die Konfigurations-Activity 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 Widgetkonfiguration überspringen kann, indem Sie eine Standardwidgetkonfiguration bereitstellen.

Nutzern ermöglichen, platzierte Widgets neu zu konfigurieren

Wenn Sie Nutzern die Möglichkeit geben möchten, vorhandene Widgets neu zu konfigurieren, geben Sie das reconfigurable Flag im widgetFeatures Attribut 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 Reconfigure (Neu konfigurieren) tippen, die in Abbildung 1 mit 1 gekennzeichnet ist.

Standardkonfiguration des Widgets verwenden

Sie können die Widgetnutzung nahtloser gestalten, indem Sie Nutzern die Möglichkeit geben, den anfänglichen Konfigurationsschritt zu überspringen. Geben Sie dazu sowohl das configuration_optional als auch das reconfigurable Flag im widgetFeatures Feld an. Dadurch wird das Starten der Konfigurations-Activity umgangen, nachdem ein Nutzer das Widget hinzugefügt hat. Wie bereits erwähnt, kann der Nutzer das Widget später trotzdem neu konfigurieren. Bei einem Uhr-Widget kann beispielsweise die anfängliche Konfiguration umgangen und standardmäßig die Zeitzone des Geräts angezeigt werden.

Hier ein Beispiel dafür, wie Sie Ihre Konfigurations-Activity sowohl als neu konfigurierbar als auch als optional kennzeichnen:

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