إدارة GlanceAppWidget وتعديلها

توضّح الأقسام التالية طريقة تعديل GlanceAppWidget وإدارة حالته.

إدارة حالة واحدة (GlanceAppWidget)

يتم إنشاء مثيل لفئة GlanceAppWidget المقدَّمة عند إنشاء التطبيق المصغّر أو عند الحاجة إلى تحديثه، لذا يجب أن تكون بدون حالة وسلبية.

نقطة رئيسية: تخضع التطبيقات المصغّرة للتطبيقات لعملية مختلفة. في حين أنّ النظام يستعيد محتوى واجهة المستخدم المحدّد (أي عنصر RemoteViews الأساسي)، يمكن في أي وقت التخلص من أي حالة يتم الاحتفاظ بها في الذاكرة، مثل نطاق التطبيق.

يمكن تقسيم مفهوم الدولة إلى ما يلي:

• حالة التطبيق: حالة التطبيق أو محتواه الذي تطلبه الأداة. على سبيل المثال، قائمة بالوجهات المخزنة (أي قاعدة البيانات) التي يحددها المستخدم.
• حالة التطبيق السريع: الحالة المحدّدة ذات الصلة بأداة التطبيق فقط ولا تعدّل حالة التطبيق أو تؤثر فيها بالضرورة. على سبيل المثال، تم تحديد مربع اختيار في الأداة أو تمت زيادة العدّاد.

استخدام حالة التطبيق

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

على سبيل المثال، يسترد الرمز التالي الوجهات من ذاكرة التخزين المؤقت للذاكرة من طبقة المستودع، ويعرض قائمة الوجهات المخزنة، ويعرض واجهة مستخدم مختلفة بناءً على حالتها:

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، تتم استضافة أدوات التطبيقات في عملية مختلفة. تترجم ميزة "نظرة سريعة" المحتوى إلى RemoteViews ويرسله إلى المضيف. ولتعديل المحتوى، على ميزة "نظرة سريعة" إعادة إنشاء 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 Coroutines على Android للحصول على مزيد من التفاصيل حول الكوروتينات.