使用 Glance 处理错误

从 Android 15 开始，系统包含用于改进 Glance 错误处理的 API 功能。本页介绍了与这些 API 相关的一些最佳实践。

在非可组合项组件周围使用 try-catch 块

Compose 不允许在可组合项周围使用 try-catch 块，但允许您将应用的其他逻辑封装在这些块中。这样，您就可以对错误视图使用 Compose，如以下示例所示：

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.Glance 1.0 默认错误布局

图 2.Glance 1.1.0 默认错误布局

Glance 允许开发者在组合失败时提供 XML 布局作为后备。这意味着 Compose 代码中存在错误。如果应用代码中存在未捕获的错误，系统也会显示此错误界面。

class UpgradeWidget : GlanceAppWidget(errorUiLayout = R.layout.error_layout)

此布局是一种静态布局，用户无法与其互动，但在紧急情况下非常有用。

图 3.自定义错误布局示例

向默认错误界面添加操作

从 Glance 1.1.0 开始，您可以使用 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>

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 的待处理 intent

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 中处理 intent

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