管理及更新 GlanceAppWidget

以下各節將說明如何更新 GlanceAppWidget 及管理其設定 時間。

管理「GlanceAppWidget」狀態

每當小工具出現例項時,提供的 GlanceAppWidget 類別就會例項化 建立或需要更新,因此應具備「無狀態」和「被動」狀態。

狀態的概念可分為下列幾類:

  • 應用程式狀態:應用程式要求的狀態或內容, 例如,由 Google 定義的儲存目的地 (例如資料庫) 清單, 使用者。
  • 資訊一覽狀態:只與應用程式小工具相關的特定狀態 且不一定會修改或影響應用程式的狀態。舉例來說 已在小工具中選取核取方塊,或加大計數器。

使用應用程式狀態

應用程式小工具應被動。每個應用程式都負責管理 並處理狀態,例如閒置、載入中和反映錯誤 。

例如,以下程式碼會從記憶體內擷取目的地 從存放區層快取、提供儲存的目的地清單,以及 根據狀態顯示不同的 UI:

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 狀態」一節所述,應用程式 小工具的代管程序不同。資訊一覽可將內容翻譯成 實際 RemoteViews,並傳送給主機。如要更新內容,查看資訊一覽 必須重新建立 RemoteViews 並再次傳送。

如要傳送更新,請呼叫 GlanceAppWidget 例項的 update 方法, 提供 contextglanceId

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

如要進一步瞭解協同程式,請參閱「Android 上的 Kotlin 協同程式」。