Nutzern erlauben, App-Widgets zu konfigurieren

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

Wenn Sie zulassen möchten, dass Nutzer die Einstellungen Ihres Widgets konfigurieren können, erstellen Sie ein Widget Konfiguration 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 Host des App-Widgets startet es mit der ACTION_APPWIDGET_CONFIGURE Aktion, 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>

Deklarieren Sie die Aktivität in der Datei AppWidgetProviderInfo.xml mit dem android:configure-Attribut. Weitere Informationen zu deklarieren dieser Datei. Hier ist ein Beispiel fü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, weil der Launcher außerhalb des Paketumfangs 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 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. Es liegt in der Verantwortung der Konfigurationsaktivität, eine Aktualisierung von AppWidgetManager beim ersten Erstellen des Widgets. 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 das Ergebnis der Konfiguration und aktualisiert 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

Im Folgenden finden Sie eine Zusammenfassung der Schritte zum ordnungsgemäßen Aktualisieren des Widgets und zum Schließen des Widgets 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 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();
   

Weitere Informationen finden Sie in der ListWidgetConfigureActivity.kt Beispielklasse auf GitHub.

Konfigurationsoptionen für Widgets

Standardmäßig startet der App-Widget-Host die Konfigurationsaktivität nur einmal. nachdem der Nutzer das Widget seinem Startbildschirm hinzugefügt hat. Sie haben jedoch kann Optionen angeben, mit denen Sie Nutzern die Neukonfiguration bestehender Widgets oder die anfängliche Widget-Konfiguration überspringen, indem Sie eine Standard-Widget-Konfiguration bereitstellen.

Hinweis :Diese Optionen sind erst ab Android 12 (API-Level 31) verfügbar. Ich für frühere Versionen von Android angeben, aber das System ignoriert und das Standardverhalten angewendet wird.

Nutzern ermöglichen, platzierte Widgets neu zu konfigurieren

Damit Nutzer vorhandene Widgets neu konfigurieren können, geben Sie die Option reconfigurable Flag im widgetFeatures Attribut von appwidget-provider. Weitere Informationen finden Sie in der Anleitung zur Deklaration der AppWidgetProviderInfo.xml-Datei für weitere Informationen Informationen. 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, 1 in Abbildung 1.

<ph type="x-smartling-placeholder">

</ph>

Abbildung 1. Widget Neu konfigurieren.

Hinweis: Das Flag reconfigurable wurde in Android 9 (API-Level 28) eingeführt, aber Diese Funktion wurde erst ab Android 12 umfassend unterstützt.

Standardkonfiguration des Widgets verwenden

Sie können die Widget-Nutzung nahtloser gestalten, indem Sie Nutzern die Möglichkeit bieten, die ersten Konfigurationsschritts. Geben Sie dazu sowohl das Feld configuration_optional und reconfigurable im Feld widgetFeatures. Dadurch wird Folgendes umgangen: Starten der Konfigurationsaktivität, nachdem ein Nutzer das Widget hinzugefügt hat. Wie bereits erwähnt aber vorher 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>