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

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

از بلوک try-catch در اطراف عناصر غیرترکیبی استفاده کنید

‫Compose اجازه نمی‌دهد بلوک‌های try-catch را پیرامون عناصر ترکیبی قرار دهید، اما به شما امکان می‌دهد منطق دیگر برنامه‌تان را در این بلوک‌ها بپیچید. این کار به شما امکان می‌دهد از «نوشتن» برای نمای خطای خود استفاده کنید، همان‌طور که در مثال زیر نشان داده شده است:

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)
    }
}
GlanceSnippets.kt

چیدمان خطای پیش‌فرض

اگر استثنای مدیریت‌نشده یا خطای «نوشتن» وجود داشته باشد، Glance چیدمان خطای پیش‌فرضی را نمایش می‌دهد:

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

class UpgradeWidget : GlanceAppWidget(errorUiLayout = R.layout.error_layout) {
    // ...
}
GlanceSnippets.kt

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

از Glance نسخه ۱.۱.۰، Glance به شما امکان می‌دهد کد مدیریت خطای پیش‌فرض را ملغی کنید. به این ترتیب، می‌توانید درصورت بروز استثنای مدیریت‌نشده یا خطا در ترکیب، برگشت‌های کنش اضافه کنید.

برای استفاده از این ویژگی، تابع onCompositionError() را ملغی کنید:

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

در این تابع، Glance برای مدیریت خطا به RemoteViews API برمی‌گردد. با این کار می‌توانید چیدمان‌ها و مدیریت‌کننده‌های کنش را بااستفاده از 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)
   }
   GlanceSnippets.kt

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)
   }
   GlanceSnippets.kt

4. قصد را در GlanceAppWidgetReceiver خود مدیریت کنید:

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