Gestisci e aggiorna GlanceAppWidget

Le sezioni seguenti descrivono come aggiornare GlanceAppWidget e gestirne lo stato.

Gestisci lo stato di GlanceAppWidget

La classe GlanceAppWidget fornita viene istanziata ogni volta che il widget viene creato o richiede un aggiornamento, pertanto deve essere senza stato e passiva.

Il concetto di stato può essere suddiviso in:

• Stato applicazione: lo stato o i contenuti dell'app richiesti dal widget. Ad esempio, un elenco di destinazioni archiviate (ovvero un database) definito dall'utente.
• Stato di Glance: lo stato specifico pertinente solo al widget dell'app e che non modifica o influisce necessariamente sullo stato dell'app. Ad esempio, è stata selezionata una casella di controllo nel widget o è stato aumentato un contatore.

Utilizzare lo stato dell'applicazione

I widget delle app devono essere passivi. Ogni applicazione è responsabile della gestione del livello dati e della gestione degli stati, ad esempio inattivo, caricamento ed errore, che si riflettono nell'interfaccia utente del widget.

Ad esempio, il seguente codice recupera le destinazioni dalla cache in memoria dal livello del repository, fornisce l'elenco memorizzato delle destinazioni e mostra un'interfaccia utente diversa a seconda del suo stato:

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

Ogni volta che lo stato o i dati cambiano, è responsabilità dell'app notificare e aggiornare il widget. Per ulteriori informazioni, consulta Aggiornare GlanceAppWidget.

Aggiorna GlanceAppWidget

Puoi richiedere l'aggiornamento dei contenuti del widget utilizzando GlanceAppWidget. Come spiegato nella sezione Gestisci stato GlanceAppWidget, i widget delle app sono ospitati in un processo diverso. Glance traduce i contenuti in RemoteViews reali e li invia all'host. Per aggiornare i contenuti, Glance deve ricreare i RemoteViews e inviarli di nuovo.

Per inviare l'aggiornamento, chiama il metodo update dell'istanza GlanceAppWidget, fornendo context e glanceId:

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

Per ottenere glanceId, esegui una query su GlanceAppWidgetManager:

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

In alternativa, utilizza una delle estensioni GlanceAppWidget update:

// 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

Questi metodi possono essere chiamati da qualsiasi parte dell'applicazione. Poiché sono funzioni suspend, ti consigliamo di avviarle al di fuori dell'ambito del thread principale. Nel seguente esempio, vengono avviati in un CoroutineWorker:

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

Per ulteriori dettagli sulle coroutine, consulta la pagina Coroutine Kotlin su Android.

Quando aggiornare i widget

Aggiorna i widget immediatamente o periodicamente.

Il widget può aggiornarsi immediatamente quando l'app è attiva. Ad esempio:

• Quando un utente interagisce con un widget, attivando un'azione, una chiamata lambda o un intent per avviare un'attività.
• Quando l'utente interagisce con la tua app in primo piano o mentre l'app è già in fase di aggiornamento in risposta a un messaggio Firebase Cloud Messaging (FCM) o a una trasmissione.

In questi casi, chiama il metodo update come descritto in questa guida.

Il widget può essere aggiornato periodicamente quando l'app non è attiva. Ad esempio:

• Utilizza updatePeriodMillis per aggiornare il widget fino a una volta ogni 30 minuti.
• Utilizza WorkManager per pianificare aggiornamenti più frequenti, ad esempio ogni 15 minuti.
• Aggiorna il widget in risposta a una trasmissione.

Risorse

• Crea un widget con Glance (codelab)
• Building for the Future of Android: Widgets chapter (video)