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

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

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

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

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

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

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

ویجت‌های برنامه باید غیرفعال باشند. هر برنامه مسئول مدیریت لایه داده و مدیریت حالت‌هایی مانند بیکار بودن، بارگیری و خطای منعکس شده در رابط کاربری ویجت است.

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

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 هستند، توصیه می‌کنیم آنها را خارج از محدوده thread اصلی اجرا کنید. در مثال زیر، آنها در یک 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()
    }
}

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

چه زمانی ویجت‌ها را به‌روزرسانی کنیم

ابزارک‌ها را فوراً یا به صورت دوره‌ای به‌روزرسانی کنید.

ویجت شما می‌تواند بلافاصله پس از بیدار شدن برنامه، به‌روزرسانی شود. برای مثال:

  • وقتی کاربر با یک ویجت تعامل می‌کند، یک اکشن، یک فراخوانی لامبدا یا یک اینتنت برای راه‌اندازی یک اکتیویتی را فعال می‌کند.
  • وقتی کاربر شما در پیش‌زمینه با برنامه شما تعامل دارد، یا در حالی که برنامه در حال به‌روزرسانی در پاسخ به یک پیام یا پخش از طریق Firebase Cloud Messaging (FCM) است.

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

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

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

منابع

قبلی
معیارهای ویجت خود را پیگیری کنید
بعدی
ایجاد رابط کاربری با Glance