مدیریت خطاها با Glance

ویژگی‌های میانای برنامه‌سازی کاربردی برای بهبود مدیریت خطا در Glance از Android 15 به بعد گنجانده شده است. این صفحه روال‌های مطلوب را درباره این میاناهای برنامه‌سازی کاربردی ارائه می‌دهد.

از بلوک try-catch در اطراف مؤلفه‌های غیرقابل‌ترکیب استفاده کنید

‫Compose اجازه نمی‌دهد بلوک‌های try-catch در اطراف composableها قرار بگیرند، اما به شما اجازه می‌دهد منطق دیگر برنامه‌تان را در این بلوک‌ها قرار دهید. این به شما امکان می‌دهد از 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 یک چیدمان خطای پیش‌فرض نمایش می‌دهد:

پیام خطایی که نوع خطا را نشان می‌دهد و پیشنهادی برای اینکه کجا دنبال آن بگردید
شکل ۱. طرح‌بندی خطای پیش‌فرض Glance 1.0
چارگوشی با نوشتار «محتوا نشان داده نشد»
شکل ۲. Glance 1.1.0 default error layout

Glance به توسعه‌دهندگان اجازه می‌دهد درصورت ناموفق بودن ترکیب‌بندی، یک طرح‌بندی XML به‌عنوان جایگزین ارائه دهند. این یعنی خطایی در کد Compose وجود داشته است. این میانای کاربر خطا همچنین اگر خطای گیرانداخته‌نشده‌ای در کد برنامه‌تان داشته باشید نشان داده می‌شود.

class UpgradeWidget : GlanceAppWidget(errorUiLayout = R.layout.error_layout) {
    // ...
}
 این چیدمان یک چیدمان ایستا است که کاربر نمی‌تواند با آن تعامل داشته باشد، اما برای موارد اضطراری مناسب است.

حاوی عنوان و فیلد نوشتاری برای نمایش پیام خطا است
شکل ۳. نمونه چیدمان خطای سفارشی

افزودن کنش به واسط کاربر خطای پیش‌فرض

از 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. قصد معوقی ایجاد کنید که به 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