Nutzern erlauben, App-Widgets zu konfigurieren

App-Widgets lassen sich konfigurieren. Mit einem Uhr-Widget können Nutzer beispielsweise festlegen, welche Zeitzone angezeigt werden soll.

Wenn Sie zulassen möchten, dass Nutzer die Einstellungen Ihres Widgets konfigurieren können, erstellen Sie eine Widget-Konfiguration Activity. Diese Aktivität wird vom Host des App-Widgets automatisch gestartet. Dies geschieht entweder bei der Erstellung des Widgets oder später, je nach den von Ihnen angegebenen Konfigurationsoptionen.

Konfigurationsaktivität deklarieren

Deklariere die Konfigurationsaktivität in der Android-Manifestdatei als normale Aktivität. Der Host des App-Widgets startet es mit der Aktion ACTION_APPWIDGET_CONFIGURE, 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>

Deklariere die Aktivität in der Datei AppWidgetProviderInfo.xml 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 auf sie 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 Host des App-Widgets 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 beim Start einer Konfigurationsaktivität keine ACTION_APPWIDGET_UPDATE-Übertragung. Das bedeutet, dass die Methode onUpdate() beim Erstellen des Widgets nicht aufgerufen wird. Beim erstmaligen Erstellen des Widgets muss in der Konfigurationsaktivität eine Aktualisierung von der AppWidgetManager angefordert werden. onUpdate() wird jedoch für nachfolgende Aktualisierungen aufgerufen und nur beim ersten Mal übersprungen.

Die Code-Snippets im folgenden Abschnitt enthalten 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, liegt es in der Verantwortung der Aktivität, das Widget nach Abschluss der Konfiguration zu aktualisieren. Fordern Sie dazu direkt in AppWidgetManager eine Aktualisierung an.

Im Folgenden finden Sie eine Zusammenfassung der Schritte zum ordnungsgemäßen Aktualisieren des Widgets und zum 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 der Nutzer die Aktivität beendet, bevor das Ende erreicht ist, benachrichtigt das System den App-Widget-Host, dass die Konfiguration abgebrochen wurde und der Host das Widget nicht hinzufügt:

    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();

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

Konfigurationsoptionen für Widgets

Standardmäßig startet der App-Widget-Host die Konfigurationsaktivität nur einmal, und zwar sofort, nachdem der Nutzer das Widget zu seinem Startbildschirm hinzugefügt hat. Sie können jedoch Optionen angeben, mit denen Nutzer vorhandene Widgets neu konfigurieren oder die anfängliche Widgetkonfiguration überspringen können, indem Sie eine Standard-Widget-Konfiguration angeben.

Nutzern ermöglichen, platzierte Widgets neu zu konfigurieren

Damit Nutzer vorhandene Widgets neu konfigurieren können, geben Sie im Attribut widgetFeatures von appwidget-provider das Flag reconfigurable an. Weitere Informationen finden Sie in der Anleitung zum Deklarieren der Datei AppWidgetProviderInfo.xml. Beispiel:

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

Nutzer können ihr Widget neu konfigurieren, indem sie das Widget berühren und halten und dann auf die Schaltfläche Neu konfigurieren tippen, die in Abbildung 1 mit 1 gekennzeichnet ist.

Die Schaltfläche wird rechts unten angezeigt
Abbildung 1. Widget Neu konfigurieren.

Standardkonfiguration des Widgets verwenden

Du kannst das Widget nahtloser nutzen, wenn Nutzer den ersten Konfigurationsschritt überspringen können. 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 immer noch neu konfigurieren. Ein Uhr-Widget kann beispielsweise die Erstkonfiguration umgehen und standardmäßig die Zeitzone des Geräts anzeigen.

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

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