GlanceAppWidget verwalten und aktualisieren

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

GlanceAppWidget-Status verwalten

Die angegebene GlanceAppWidget-Klasse wird instanziiert, wenn das Widget erstellt wird oder ein Update benötigt. 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 der vom Nutzer definierten gespeicherten Ziele (d.h. Datenbank).
• Glance-Status: Der spezifische Status, der nur für das App-Widget relevant ist und nicht unbedingt den Status der App ändert oder beeinflusst. Beispiel: Im Widget wurde ein Kä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 Status wie „Inaktiv“, „Wird geladen“ und „Fehler“ verantwortlich, die in der Widget-UI angezeigt werden.

Im folgenden Code werden beispielsweise die Ziele aus dem In-Memory-Cache aus der Repository-Ebene abgerufen, die gespeicherte Liste der Ziele bereitgestellt und je nach Status eine andere Benutzeroberfläche 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

Du kannst die Aktualisierung deiner Widget-Inhalte über GlanceAppWidget beantragen. Wie im Abschnitt GlanceAppWidget-Status 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. Wenn Glance die Inhalte aktualisieren möchte, muss es die RemoteViews neu erstellen und noch einmal senden.

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

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

Fragen Sie die GlanceAppWidgetManager ab, um die glanceId abzurufen:

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 aus aufgerufen werden. Da es sich um suspend-Funktionen handelt, empfehlen wir, sie außerhalb des Hauptthreads 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 unter Android.

Wann Widgets aktualisiert werden sollten

Widgets entweder sofort oder regelmäßig aktualisieren.

Wenn Ihre App aktiv ist, kann das Widget sofort aktualisiert werden. Beispiel:

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

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

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.
• Widget als Reaktion auf einen Broadcast aktualisieren

Ressourcen

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