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

وعندما تتغيّر الحالة أو البيانات، يكون التطبيق مسؤولاً عن إرسال إشعار وتعديل الأداة. راجِع تعديل GlanceAppWidget للحصول على مزيد من المعلومات.

تحديث "GlanceAppWidget"

يمكنك طلب تعديل محتوى تطبيقك المصغّر باستخدام GlanceAppWidget. كما هو موضّح في قسم حالة GlanceAppWidget، تتم استضافة أدوات التطبيقات في عملية مختلفة. تترجم ميزة "نظرة سريعة" المحتوى إلى RemoteViews وترسله إلى المضيف. لتعديل المحتوى، على Glance إعادة إنشاء RemoteViews وإرسالها مرة أخرى.

لإرسال التعديل، استدعِ الدالة update من مثيل GlanceAppWidget، مع توفير context وglanceId:

MyAppWidget().update(context, glanceId)
GlanceSnippets.kt

للحصول على glanceId، أرسِل طلب بحث إلى GlanceAppWidgetManager:

val manager = GlanceAppWidgetManager(context)
val widget = GlanceSizeModeWidget()
val glanceIds = manager.getGlanceIds(widget.javaClass)
glanceIds.forEach { glanceId ->
    widget.update(context, glanceId)
}
GlanceSnippets.kt

بدلاً من ذلك، استخدِم إحدى إضافات 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
}
GlanceSnippets.kt

يمكن استدعاء هذه الطرق من أي جزء من تطبيقك. بما أنّها دوال 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()
    }
}
GlanceSnippets.kt

يمكنك الاطّلاع على الكوروتينات في لغة Kotlin على نظام التشغيل Android للحصول على مزيد من التفاصيل حول الكوروتينات.

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

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

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

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

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

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

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

المراجع

• إنشاء تطبيق مصغّر باستخدام Glance (درس تطبيقي حول الترميز)
• بناء مستقبل Android: فصل التطبيقات المصغّرة (فيديو)