Nutzern erlauben, App-Widgets zu konfigurieren

App-Widgets können konfiguriert werden. Mit einem Uhr-Widget können Nutzende 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 App-Widget-Host startet es mit der Aktion ACTION_APPWIDGET_CONFIGURE. Daher muss die Aktivität diesen Intent 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 AppWidgetProviderInfo.xml-Datei mit dem Attribut android:configure. Weitere Informationen zum Deklarieren dieser Datei Hier ein Beispiel für die Deklaration der Konfigurationsaktivität:

<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, weil der Launcher außerhalb des Paketumfangs auf sie 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

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

  • Der Host des App-Widgets ruft die Konfigurationsaktivität und die Konfiguration Aktivität muss immer ein Ergebnis zurückgeben. Das Ergebnis muss das App-Widget enthalten. ID, die vom Intent übergeben wurde, der die Aktivität gestartet hat und im Intent gespeichert ist Extras als EXTRA_APPWIDGET_ID
  • Das System sendet die ACTION_APPWIDGET_UPDATE wird gesendet, wenn eine Konfigurationsaktivität gestartet wird. Das bedeutet, dass keine rufen Sie die Methode onUpdate() auf, 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 über die 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 aus dem Intent ab, über den 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. 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. Wenn die Konfiguration abgeschlossen ist, rufen Sie eine Instanz des AppWidgetManager durch Aufrufen von getInstance(Context):

    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, 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 Erstkonfiguration von Widgets überspringen können, indem Sie eine Standardkonfiguration für Widgets angeben.

Nutzern das Neukonfigurieren platzierter Widgets ermöglichen

Damit Nutzer vorhandene Widgets neu konfigurieren können, geben Sie die Option reconfigurable Flag im widgetFeatures Attribut von appwidget-provider. Weitere Informationen finden Sie im Leitfaden zur Deklaration 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 & das Widget gedrückt halten und auf auf die Schaltfläche Neu konfigurieren, die mit der Beschriftung 1 in Abbildung 1.

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

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 hat, kann der Nutzer das Widget immer noch neu konfigurieren. danach. 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>