مدیریت و به‌روزرسانی 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 توضیح داده شد، ابزاره‌های برنامه در فرایند متفاوتی میزبانی می‌شوند. «نگاه سریع» محتوا را به 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»‏ (FCM) یا همه‌فرستی درحال به‌روزرسانی است.

در این موارد، روش update را همان‌طور که در این راهنما شرح داده شده است فراخوانی کنید.

وقتی برنامه‌تان فعال نیست، ابزاره‌تان می‌تواند به‌طور دوره‌ای به‌روز شود. برای مثال:

  • از updatePeriodMillis برای به‌روزرسانی ابزاره تا یک بار در هر ۳۰ دقیقه استفاده کنید.
  • از WorkManager برای زمان‌بندی به‌روزرسانی‌های مکررتر، مثلاً هر ۱۵ دقیقه، استفاده کنید.
  • ابزاره را در پاسخ به پخش به‌روز کنید.

منابع

قبلی
ردیابی سنجه‌های ابزاره
بعدی
ساختن میانای کاربر با Glance