GlanceAppWidget verwalten und aktualisieren

In den folgenden Abschnitten wird beschrieben, wie Sie GlanceAppWidget aktualisieren und den Status verwalten.

GlanceAppWidget-Status verwalten

Die bereitgestellte GlanceAppWidget-Klasse wird immer dann instanziiert, wenn das Widget erstellt wird oder eine Aktualisierung erforderlich ist. Sie sollte daher zustandslos und passiv sein.

Das Konzept des Status kann in Folgendes unterteilt werden:

• Anwendungsstatus: Der Status oder Inhalt der App, der für das Widget erforderlich ist. Beispiel: Eine Liste gespeicherter Ziele (d.h. Datenbank), die vom Nutzer definiert wurde.
• Glance-Status: Der spezifische Status, der nur für das App-Widget relevant ist und den Status der App nicht unbedingt ändert oder beeinflusst. Beispiel: Im Widget wurde ein Kontrollkästchen ausgewählt oder ein Zähler wurde erhöht.

Anwendungsstatus verwenden

App-Widgets sollten passiv sein. Jede Anwendung ist für die Verwaltung der Datenschicht und die Verarbeitung der Zustände verantwortlich, z. B. für die Zustände „inaktiv“, „Wird geladen“ und „Fehler“, die in der Widget-UI angezeigt werden.

Mit dem folgenden Code werden beispielsweise die Ziele aus dem In-Memory-Cache der Repository-Ebene abgerufen, die gespeicherte Liste der Ziele bereitgestellt und je nach Status eine andere UI angezeigt:

class DestinationAppWidget : GlanceAppWidget() {

    // ...

    @Composable
    fun MyContent() {
        val repository = remember { DestinationsRepository.getInstance() }
        // Retrieve the cache data everytime the content is refreshed
        val destinations by repository.destinations.collectAsState(State.Loading)

        when (destinations) {
            is State.Loading -> {
                // show loading content
            }

            is State.Error -> {
                // show widget error content
            }

            is State.Completed -> {
                // show the list of destinations
            }
        }
    }
}
GlanceSnippets.kt

Wenn sich der Status oder die Daten ändern, muss die App das Widget benachrichtigen und aktualisieren. Weitere Informationen finden Sie unter GlanceAppWidget aktualisieren.

GlanceAppWidget aktualisieren

Sie können die Aktualisierung Ihrer Widget-Inhalte mit GlanceAppWidget anfordern. Wie im Abschnitt GlanceAppWidgetStatus verwalten erläutert, werden App Widgets in einem anderen Prozess gehostet. Glance übersetzt den Inhalt in tatsächliche RemoteViews und sendet sie an den Host. Um den Inhalt zu aktualisieren, muss Glance die RemoteViews neu erstellen und noch einmal senden.

Rufen Sie zum Senden der Aktualisierung die Methode update der GlanceAppWidget-Instanz auf und geben Sie context und glanceId an:

MyAppWidget().update(context, glanceId)
GlanceSnippets.kt

Rufen Sie die glanceId mit einer Abfrage von GlanceAppWidgetManager ab:

val manager = GlanceAppWidgetManager(context)
val widget = GlanceSizeModeWidget()
val glanceIds = manager.getGlanceIds(widget.javaClass)
glanceIds.forEach { glanceId ->
    widget.update(context, glanceId)
}
GlanceSnippets.kt

Alternativ können Sie eine der GlanceAppWidget update-Erweiterungen verwenden:

// Updates all placed instances of MyAppWidget
MyAppWidget().updateAll(context)

// Iterate over all placed instances of MyAppWidget and update if the state of
// the instance matches the given predicate
MyAppWidget().updateIf<State>(context) { state ->
    state == State.Completed
}
GlanceSnippets.kt

Diese Methoden können von jedem Teil Ihrer Anwendung aufgerufen werden. Da es sich um suspend-Funktionen handelt, empfehlen wir, sie außerhalb des Hauptthreadbereichs zu starten. Im folgenden Beispiel werden sie in einem CoroutineWorker gestartet:

class DataSyncWorker(
    val context: Context,
    val params: WorkerParameters,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        // Fetch data or do some work and then update all instance of your widget
        MyAppWidget().updateAll(context)
        return Result.success()
    }
}
GlanceSnippets.kt

Weitere Informationen zu Koroutinen finden Sie unter Kotlin-Koroutinen in Android.

Wann sollten Widgets aktualisiert werden?

Aktualisieren Sie Widgets entweder sofort oder regelmäßig.

Ihr Widget kann sofort aktualisiert werden, wenn Ihre App aktiv ist. Beispiel:

• Wenn ein Nutzer mit einem Widget interagiert und dadurch eine Aktion, einen Lambda-Aufruf oder eine Intent-Aktivität ausgelöst wird.
• Wenn Ihr Nutzer im Vordergrund mit Ihrer App interagiert oder während die App bereits als Reaktion auf eine Firebase Cloud Messaging-Nachricht (FCM) oder eine Broadcast-Nachricht aktualisiert wird.

Rufen Sie in diesen Fällen die update Methode auf, wie in diesem Leitfaden beschrieben.

Ihr Widget kann regelmäßig aktualisiert werden, wenn Ihre App nicht aktiv ist. Beispiel:

• Verwenden Sie updatePeriodMillis, um das Widget bis zu einmal alle 30 Minuten zu aktualisieren.
• Verwenden Sie WorkManager, um häufigere Aktualisierungen zu planen, z. B. alle 15 Minuten.
• Aktualisieren Sie das Widget als Reaktion auf eine Broadcast-Nachricht.

Ressourcen

• Widgets mit Glance erstellen (Codelab)
• Building for the Future of Android: Widgets chapter (Video)