Gerenciar e atualizar o GlanceAppWidget

As seções a seguir descrevem como atualizar o GlanceAppWidget e gerenciar o estado dele.

Gerenciar o estado do GlanceAppWidget

A classe GlanceAppWidget fornecida é instanciada sempre que o widget é criado ou exige uma atualização. Portanto, ela precisa ser sem estado e passiva.

O conceito de estado pode ser dividido da seguinte maneira:

  • Estado do aplicativo: o estado ou conteúdo do app exigido pelo widget. Por exemplo, uma lista de destinos armazenados (ou seja, banco de dados) definida pelo usuário.
  • Estado do Glance: o estado específico que é relevante apenas para o widget do app e não modifica nem afeta necessariamente o estado do app. Por exemplo, uma caixa de seleção foi marcada no widget ou um contador foi aumentado.

Usar o estado do aplicativo

Os widgets de apps precisam ser passivos. Cada aplicativo é responsável por gerenciar a camada de dados e processar os estados, como inativo, carregamento e erro refletido na interface do widget.

Por exemplo, o código a seguir recupera os destinos do cache na memória da camada do repositório, fornece a lista armazenada de destinos e mostra uma interface diferente dependendo do estado:

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

Sempre que o estado ou os dados mudam, é responsabilidade do app notificar e atualizar o widget. Consulte Atualizar o GlanceAppWidget para mais informações.

Atualizar o GlanceAppWidget

Você pode solicitar a atualização do conteúdo do widget usando GlanceAppWidget. Conforme explicado na seção Gerenciar GlanceAppWidget estado, os widgets de apps são hospedados em um processo diferente. O Glance traduz o conteúdo em RemoteViews reais e os envia ao host. Para atualizar o conteúdo, o Glance precisa recriar os RemoteViews e enviá-los novamente.

Para enviar a atualização, chame o método update da instância GlanceAppWidget, fornecendo o context e o glanceId:

MyAppWidget().update(context, glanceId)

Para receber o glanceId, consulte o GlanceAppWidgetManager:

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

Como alternativa, use uma das extensões 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
}

Esses métodos podem ser chamados de qualquer parte do aplicativo. Como são funções suspend, recomendamos iniciá-las fora do escopo da linha de execução principal. No exemplo a seguir, elas são iniciadas em um 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()
    }
}

Consulte Corrotinas do Kotlin no Android para mais detalhes sobre corrotinas.

Quando atualizar widgets

Atualize os widgets imediatamente ou periodicamente.

O widget pode ser atualizado imediatamente quando o app está ativo. Por exemplo:

  • Quando um usuário interage com um widget, acionando uma ação, uma chamada lambda ou uma intent para iniciar uma atividade.
  • Quando o usuário interage com o app em primeiro plano ou enquanto ele já está sendo atualizado em resposta a uma mensagem do Firebase Cloud Messaging (FCM) ou uma transmissão.

Nesses casos, chame o update método conforme descrito neste guia.

O widget pode ser atualizado periodicamente quando o app não está ativo. Por exemplo:

  • Use updatePeriodMillis para atualizar o widget até uma vez a cada 30 minutos.
  • Use WorkManager para agendar atualizações mais frequentes, como a cada 15 minutos.
  • Atualize o widget em resposta a uma transmissão.

Recursos

Anterior
Acompanhar métricas do widget
Avançar
Criar uma interface com o Glance