Как управлять GlanceAppWidget и обновлять его

В следующих разделах описывается, как обновлять GlanceAppWidget и управлять его состоянием.

Управление состоянием GlanceAppWidget

Экземпляр предоставленного класса GlanceAppWidget создается каждый раз, когда создается или обновляется виджет, поэтому он должен быть без сохранения состояния и пассивным.

Понятие состояния можно разделить на следующие категории:

  • Состояние приложения. Состояние или контент приложения, необходимые для работы виджета. Например, список сохраненных пунктов назначения (т.е. база данных), определенных пользователем.
  • Состояние Glance. Определенное состояние, которое относится только к виджету приложения и не обязательно изменяет или влияет на состояние приложения. Например, в виджете был установлен флажок или увеличилось значение счетчика.

Использовать статус приложения

Виджеты приложений должны быть пассивными. Каждое приложение отвечает за управление слоем данных и обработку состояний, таких как бездействие, загрузка и ошибка, отраженных в пользовательском интерфейсе виджета.

Например, следующий код извлекает пункты назначения из кеша памяти из уровня репозитория, предоставляет сохраненный список пунктов назначения и отображает другой пользовательский интерфейс в зависимости от его состояния:

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

При изменении состояния или данных приложение должно уведомить виджет и обновить его. Подробнее о том, как обновить GlanceAppWidget…

Обновление ПО: GlanceAppWidget

Вы можете запросить обновление контента виджета с помощью GlanceAppWidget. Как объясняется в разделе Управление состоянием GlanceAppWidget, виджеты приложений размещаются в другом процессе. Glance преобразует контент в RemoteViews и отправляет их хосту. Чтобы обновить контент, Glance должен заново создать RemoteViews и отправить их.

Чтобы отправить обновление, вызовите метод update экземпляра GlanceAppWidget, указав context и glanceId:

MyAppWidget().update(context, glanceId)

Чтобы получить glanceId, отправьте запрос к GlanceAppWidgetManager:

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

Вы также можете использовать одно из расширений 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
}

Эти методы можно вызывать из любой части приложения. Поскольку это функции suspend, мы рекомендуем запускать их вне области основного потока. В примере ниже они запускаются в 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()
    }
}

Подробнее о сопрограммах Kotlin в Android…

Когда обновлять виджеты

Обновляйте виджеты сразу или периодически.

Виджет может обновляться сразу, когда приложение активно. Пример:

  • Когда пользователь взаимодействует с виджетом, запуская действие, вызов лямбда-функции или намерение запустить действие.
  • Когда пользователь взаимодействует с приложением на переднем плане или когда приложение уже обновляется в ответ на сообщение Firebase Cloud Messaging (FCM) или трансляцию.

В таких случаях вызывайте метод update, как описано в этом руководстве.

Виджет может периодически обновляться, когда приложение неактивно. Пример:

  • Используйте updatePeriodMillis, чтобы обновлять виджет не чаще одного раза в 30 минут.
  • Используйте WorkManager, чтобы запланировать более частое обновление, например каждые 15 минут.
  • Обновление виджета в ответ на широковещательное сообщение.

Ресурсы

Назад
Как отслеживать показатели для виджета
Далее
Как создавать интерфейсы с помощью Glance