إدارة 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.

متى يجب تحديث التطبيقات المصغّرة؟

تعديل التطبيقات المصغّرة إما على الفور أو بشكل دوري

يمكن تحديث التطبيق المصغّر فورًا عندما يكون تطبيقك نشطًا. على سبيل المثال:

  • عندما يتفاعل المستخدم مع تطبيق مصغّر، يتم تفعيل إجراء أو استدعاء دالة lambda أو طلب لبدء نشاط.
  • عندما يتفاعل المستخدم مع تطبيقك في المقدّمة، أو أثناء تحديث التطبيق استجابةً لرسالة أو بث من "مراسلة Firebase السحابية" (FCM)

في هذه الحالات، يمكنك استدعاء طريقة update كما هو موضّح في هذا الدليل.

يمكن تحديث التطبيق المصغّر بشكل دوري عندما لا يكون تطبيقك نشطًا. على سبيل المثال:

  • استخدِم updatePeriodMillis لتعديل التطبيق المصغّر مرة واحدة كل 30 دقيقة كحد أقصى.
  • استخدِم WorkManager لجدولة تعديلات أكثر تكرارًا، مثل كل 15 دقيقة.
  • تعديل التطبيق المصغّر استجابةً لعملية بث

الموارد

السابق
تتبُّع مقاييس تطبيقك المصغّر
التالي
إنشاء واجهة مستخدم من خلال ميزة "نظرة سريعة"