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

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

استخدام كتلة تجريبية حول المكوّنات غير القابلة للإنشاء

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

provideContent {
       var isError = false;
       var data = null
       try {
           val repository = (context.applicationContext as MyApplication).myRepository
           data = repository.loadData()
       } catch (e: Exception) {
           isError = true;
           //handleError
       }

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

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

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

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

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

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>

  1. إلغاء الدالة 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)
}

  1. أنشئ نية معلّقة تشير إلى GlanceAppWidgetReceiver.
private fun getErrorIntent(context: Context, throwable: Throwable): PendingIntent {
    val intent = Intent(context, UpgradeToHelloWorldPro::class.java)
    intent.setAction("widgetError")
    return PendingIntent.getBroadcast(context, 0, intent, PendingIntent.FLAG_IMMUTABLE)
}

  1. التعامل مع الهدف في "GlanceAppWidgetReceiver"
override fun onReceive(context: Context, intent: Intent) {
   super.onReceive(context, intent)
   Log.e("ErrorOnClick", "Button was clicked.");
}