إدارة 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 الحالة، يتم استضافة التطبيقات المصغّرة في عملية مختلفة. تحوّل 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، ننصحك بتشغيلها خارج نطاق سلسلة المحادثات الرئيسية. في المثال التالي، يتم تشغيلها في 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 لتعديل التطبيق المصغّر مرة واحدة كل 30 دقيقة كحد أقصى.
  • استخدِم WorkManager لجدولة تعديلات أكثر تكرارًا، مثلاً كل 15 دقيقة.
  • عدِّل التطبيق المصغّر استجابةً لبث.

الموارد

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