التعامل مع الأخطاء من خلال ميزة "نظرة سريعة"

تتوفّر ميزات واجهة برمجة التطبيقات لتحسين معالجة الأخطاء في Glance بدءًا من الإصدار 15 من نظام التشغيل Android. تقدّم هذه الصفحة أفضل الممارسات المتعلّقة بواجهات برمجة التطبيقات هذه.

استخدام كتلة try-catch حول المكوّنات غير القابلة للتركيب

لا تسمح Compose باستخدام كتل try-catch حول الدوال المركّبة، ولكنها تتيح لك تضمين المنطق الآخر لتطبيقك في هذه الكتل. يتيح لك ذلك استخدام Compose لعرض رسالة الخطأ، كما هو موضّح في المثال التالي:

provideContent {
    var isError = false
    var data = listOf<String>()
    try {
        val repository = (context.applicationContext as MyApplication).myRepository
        data = repository.loadData()
    } catch (e: Exception) {
        isError = true
        // TODO: handle error
    }

    if (isError) {
        ErrorView()
    } else {
        Content(data)
    }
}

التنسيق التلقائي للأخطاء

إذا حدث استثناء لم يتم رصده أو خطأ في Compose، يعرض Glance تنسيق خطأ تلقائيًا:

رسالة خطأ تعرض نوع الخطأ واقتراحًا لمكان البحث عنه
الشكل 1: التنسيق التلقائي للأخطاء في الإصدار 1.0 من Glance
مربّع يتضمّن النص &quot;يتعذّر عرض المحتوى&quot;
الشكل 2. تنسيق الخطأ التلقائي في الإصدار 1.1.0 من Glance

تتيح Glance للمطوّرين توفير تنسيق XML كخيار احتياطي في حال تعذّر الإنشاء. يعني ذلك حدوث خطأ في رمز Compose. تظهر واجهة المستخدم الخاصة بهذا الخطأ أيضًا إذا كان لديك خطأ لم يتم رصده في رمز تطبيقك.

class UpgradeWidget : GlanceAppWidget(errorUiLayout = R.layout.error_layout) {
    // ...
}
 هذا التنسيق هو تنسيق ثابت لا يمكن للمستخدم التفاعل معه، ولكنه جيد في حالات الطوارئ.

يحتوي على عنوان وحقل نصي لعرض رسالة خطأ
الشكل 3: مثال على تنسيق مخصّص لرسالة الخطأ

إضافة إجراءات إلى واجهة المستخدم التلقائية للأخطاء

اعتبارًا من الإصدار 1.1.0 من Glance، يتيح لك Glance إلغاء رمز معالجة الأخطاء التلقائي. بهذه الطريقة، يمكنك إضافة عمليات استدعاء الإجراءات في حالة حدوث استثناء أو خطأ غير متوقع في التركيب.

لاستخدام هذه الميزة، يجب إلغاء دالة onCompositionError():

GlanceAppWidget.onCompositionError(
    context: Context,
    glanceId: GlanceId,
    appWidgetId: Int,
    throwable: Throwable
)

في هذه الدالة، تعود Glance إلى واجهة برمجة التطبيقات RemoteViews لمعالجة الأخطاء. يتيح لك ذلك تحديد التنسيقات ومعالِجات الإجراءات باستخدام XML.

توضّح لك الأمثلة التالية، خطوة بخطوة، كيفية إنشاء واجهة مستخدم لرسائل الخطأ تتضمّن زرًا لإرسال الملاحظات:

  1. اكتب ملف error_layout.xml:

    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   style="@style/Widget.MyApplication.AppWidget.Error"
   android:id="@android:id/background"
   android:layout_width="match_parent"
   android:textSize="24sp"
   android:layout_height="match_parent"
   android:orientation="vertical">

   <TextView
       android:id="@+id/error_title_view"
       android:layout_width="match_parent"
       android:textColor="@color/white"
       android:textFontWeight="800"
       android:layout_height="wrap_content"
       android:text="Example Widget Error" />

   <LinearLayout
       android:layout_width="match_parent"
       android:orientation="horizontal"
       android:paddingTop="4dp"
       android:layout_height="match_parent">

       <ImageButton
        android:layout_width="64dp"
        android:layout_height="64dp"
        android:layout_gravity="center"
        android:tint="@color/white"
        android:id="@+id/error_icon"
        android:src="@drawable/heart_broken_fill0_wght400_grad0_opsz24"
       />
       <TextView
           android:id="@+id/error_text_view"
           android:layout_width="wrap_content"
           android:textColor="@color/white"
           android:layout_height="wrap_content"
           android:layout_gravity="center"
           android:padding="8dp"
           android:textSize="16sp"
           android:layout_weight="1"
           android:text="Useful Error Message!" />
   </LinearLayout>

</LinearLayout>

  2. إلغاء دالة onCompositionError:

    override fun onCompositionError(
    context: Context, glanceId: GlanceId, appWidgetId: Int, throwable: Throwable
) {
    val rv = RemoteViews(context.packageName, R.layout.error_layout)
    rv.setTextViewText(
        R.id.error_text_view,
        "Error was thrown. \nThis is a custom view \nError Message: `${throwable.message}`"
    )
    rv.setOnClickPendingIntent(R.id.error_icon, getErrorIntent(context, throwable))
    AppWidgetManager.getInstance(context).updateAppWidget(appWidgetId, rv)
}

  3. أنشئ intent مؤجّلة تشير إلى GlanceAppWidgetReceiver:

    private fun getErrorIntent(context: Context, throwable: Throwable): PendingIntent {
    val intent = Intent(context, UpgradeToHelloWorldPro::class.java)
    intent.action = "widgetError"
    return PendingIntent.getBroadcast(context, 0, intent, PendingIntent.FLAG_IMMUTABLE)
}

  4. تعامَل مع الطلب في GlanceAppWidgetReceiver:

    override fun onReceive(context: Context, intent: Intent) {
    super.onReceive(context, intent)
    Log.e("ErrorOnClick", "Button was clicked.")
}

السابق
تثبيت تطبيقات Glance المصغّرة داخل التطبيق
التالي
اختبار الوحدات من خلال ميزة "نظرة سريعة"