مدیریت و به‌روزرسانی GlanceAppWidget

بخش‌های زیر نحوه به‌روزرسانی GlanceAppWidget و مدیریت وضعیت آن را شرح می‌دهد.

مدیریت وضعیت GlanceAppWidget

هرگاه ابزاره ایجاد شود یا به به‌روزرسانی نیاز داشته باشد، کلاس GlanceAppWidget ارائه‌شده نمونه‌سازی می‌شود، بنابراین باید بدون وضعیت و منفعل باشد.

مفهوم حالت را می‌توان به موارد زیر تقسیم کرد:

  • وضعیت برنامه: وضعیت یا محتوای برنامه‌ای که ویجت به آن نیاز دارد. برای مثال، فهرست مقصدهای ذخیره‌شده (یعنی پایگاه داده) که توسط کاربر تعریف شده است.
  • وضعیت «نگاه سریع»: وضعیت خاصی که فقط به ابزارک برنامه مربوط است و لزوماً وضعیت برنامه را تغییر نمی‌دهد یا تحت تأثیر قرار نمی‌دهد. برای مثال، چارگوش انتخابی در ابزاره انتخاب شده است یا شمارنده افزایش یافته است.

استفاده از وضعیت برنامه

ابزاره‌های برنامه باید منفعل باشند. هر برنامه مسئول مدیریت لایه داده و مدیریت وضعیت‌ها (مثل وضعیت‌های آماده، درحال بار کردن، و خطا) است که در میانای کاربر ابزارک منعکس می‌شود.

برای مثال، کد زیر مقصدها را از حافظه نهان در لایه مخزن بازیابی می‌کند، فهرست ذخیره‌شده مقصدها را ارائه می‌دهد، و بسته به وضعیت آن، رابط کاربری متفاوتی نمایش می‌دهد:

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

هرگاه وضعیت یا داده‌ها تغییر کند، این برنامه است که باید ویجت را به‌روزرسانی کند و اعلان کند. برای اطلاعات بیشتر، Update 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