Nutzern erlauben, App-Widgets zu konfigurieren

App-Widgets können konfiguriert werden. 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 die Methode onUpdate() nicht aufgerufen wird, wenn das Widget erstellt wird. Es liegt in der Verantwortung der Konfigurationsaktivität, beim ersten Erstellen des Widgets eine Aktualisierung von AppWidgetManager anzufordern. onUpdate() wird jedoch für nachfolgende Updates aufgerufen. Es wird nur beim ersten Mal ü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 ü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. Sie können dies tun, indem Sie direkt über die AppWidgetManager eine Aktualisierung anfordern.

Hier finden Sie 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:

    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 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:

    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 entsprechend den Einstellungen des Nutzers.

  4. Wenn die Konfiguration abgeschlossen ist, rufen Sie eine Instanz von AppWidgetManager durch Aufrufen von getInstance(Context) ab:

    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. Erstellen Sie die Rückgabeabsicht, legen Sie sie 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();

Ein Beispiel finden Sie in der Beispielklasse ListWidgetConfigureActivity.kt auf GitHub.

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 Nutzer vorhandene Widgets neu konfigurieren oder die anfängliche Widget-Konfiguration überspringen können, 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. Weitere Informationen finden Sie im Leitfaden zum Deklarieren 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.

Schaltfläche wird rechts unten angezeigt
Abbildung 1. Schaltfläche Neu konfigurieren für das Widget.

Standardkonfiguration des Widgets verwenden

Sie können das Widget-Erlebnis nahtloser gestalten, indem Sie Nutzern ermöglichen, den ersten Konfigurationsschritt zu überspringen. Geben Sie dazu sowohl das Flag configuration_optional als auch das Flag reconfigurable im Feld widgetFeatures 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>