使用 Glance 创建应用 widget

以下部分介绍了如何使用 Glance 创建基本应用微件。

要点： Glance 提供了一种使用 Compose 构建应用微件的现代方法，但受 AppWidgets 和 RemoteViews 的限制。因此，Glance 使用的可组合项与 Jetpack Compose 界面不同。

在清单中声明 AppWidget

完成设置步骤后，在应用中声明 AppWidget 及其元数据。

1. 从 GlanceAppWidgetReceiver 扩展 AppWidget 接收器：

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. 在 AndroidManifest.xml 文件和关联的元数据文件中注册应用 widget 的提供程序：

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

添加 AppWidgetProviderInfo 元数据

接下来，按照创建 widget 指南中的说明在 @xml/my_app_widget_info 文件中创建并定义应用 widget 信息。

对于 Glance，唯一的区别是没有 initialLayout XML，但您必须定义一个。您可以使用库中提供的预定义加载布局：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

声明 AppWidgetProviderInfo XML

AppWidgetProviderInfo 对象用于定义 widget 的基本特性。在 XML 元数据资源文件 (res/xml/my_app_widget_info.xml) 的 <appwidget-provider> 元素内定义 AppWidgetProviderInfo：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

微件尺寸设置属性

默认的主屏幕根据定义了高度和宽度的单元格的网格在其窗口中放置 widget。大多数主屏幕只允许微件采用网格单元的整数倍大小，例如水平方向上为 2 个单元格，垂直方向上为 3 个单元格。

借助微件尺寸调整属性，您可以为微件指定默认大小，并提供微件大小的下限和上限。在此背景下，widget 的默认大小是指 widget 首次添加到主屏幕时所占的大小。

下表介绍了与 widget 大小调整相关的 <appwidget-provider> 属性：

属性和说明
targetCellWidth 和 targetCellHeight（Android 12）、minWidth 和 minHeight	从 Android 12 开始，targetCellWidth 和 targetCellHeight 属性指定 widget 的默认大小（以网格单元格为单位）。在 Android 11 及更低版本中，这些属性会被忽略；如果主屏幕不支持基于网格的布局，这些属性也可以忽略。 minWidth 和 minHeight 属性指定了微件的默认大小（以 dp 为单位）。如果微件的最小宽度或高度的值与单元格的尺寸不匹配，则这些值会向上舍入到最接近的单元格大小。 我们建议您同时指定这两组属性（targetCellWidth 和 targetCellHeight，以及 minWidth 和 minHeight），以便在用户设备不支持 targetCellWidth 和 targetCellHeight 时，您的应用可以回退到使用 minWidth 和 minHeight。如果支持，targetCellWidth 和 targetCellHeight 属性优先于 minWidth 和 minHeight 属性。
minResizeWidth和 minResizeHeight	指定微件的绝对最小尺寸。这些值指定了微件小于什么尺寸会难以辨认或无法使用。使用这些属性，用户可以将微件的大小调整为小于默认微件大小。如果 minResizeWidth 属性大于 minWidth 或者未启用水平调整大小功能，系统会忽略该属性。请参阅 resizeMode。同样，如果 minResizeHeight 属性大于 minHeight 或者未启用垂直调整大小功能，系统会忽略该属性。
maxResizeWidth和 maxResizeHeight	指定 widget 的建议最大尺寸。如果这些值不是网格单元格尺寸的倍数，则会向上舍入到最接近的单元格尺寸。如果 maxResizeWidth 属性小于 minWidth 或未启用水平大小调整，则系统会忽略该属性。请参阅 resizeMode。同样，如果 maxResizeHeight 属性小于 minHeight 或未启用垂直大小调整，则系统会忽略该属性。此属性是在 Android 12 中引入的。
resizeMode	指定可以按什么规则来调整微件的大小。您可以使用此属性来让主屏幕微件在横轴上可调整大小、在纵轴上可调整大小，或者在这两个轴上均可调整大小。用户可轻触并按住微件以显示其大小调整手柄，然后拖动水平或垂直手柄以更改布局网格上的大小。resizeMode 属性的值包括 horizontal、vertical 和 none。如需将微件声明为在水平和垂直方向上均可调整大小，请使用 horizontal|vertical。

示例

为说明上表中的属性如何影响 widget 大小，假设有以下规范：

• 网格单元格的宽度为 30 dp，高度为 50 dp。
• 以下是属性规范：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

从 Android 12 开始：

使用 targetCellWidth 和 targetCellHeight 属性作为微件的默认大小。

默认情况下，该 widget 的大小为 2x2。您可以将该 widget 的大小调整为最小 2x1 或最大 4x3。

Android 11 及更低版本：

使用 minWidth 和 minHeight 属性计算 widget 的默认大小。

默认宽度 = Math.ceil(80 / 30) = 3

默认高度 = Math.ceil(80 / 50) = 2

默认情况下，微件的大小为 3x2。您可以将该 widget 调整为最小 2x1 或最大全屏。

注意： 如果您使用 SizeMode.Responsive 或 SizeMode.Exact，Jetpack Glance 会处理 provideGlance 内的布局更改，以响应动态单元格缩放。如需利用这些模式，请参阅使用 Glance 构建界面指南。

其他 widget 属性

下表介绍了与 widget 大小调整以外的质量相关的 <appwidget-provider> 属性。

属性和说明
updatePeriodMillis	定义 widget 框架通过调用 onUpdate() 回调方法从 GlanceAppWidgetReceiver 请求更新的频率。我们建议尽可能降低更新频率（不超过每小时一次），以节省电池电量。如需了解详情，请参阅概览状态管理中的何时更新 widget 部分。
initialLayout	指向用于定义 widget 在 Glance 界面组合渲染之前的加载布局的布局资源。您可以使用库中提供的预定义加载布局：@layout/glance_default_loading_layout。
configure	定义在用户添加 widget 时启动的配置 activity。请参阅本页面上的实现微件配置 Activity 部分。
description	指定要由 widget 选择器显示的 widget 说明。在 Android 12 中引入。
previewLayout（Android 12）和 previewImage（Android 11 及更低版本）	从 Android 12 开始，previewLayout 属性用于指定可缩放的预览，您会将其作为 XML 布局提供，该布局设置为 widget 的默认大小。理想情况下，此属性指向与您的设计布局匹配的静态 XML 映射。 在 Android 11 或更低版本中，previewImage 属性用于指定 widget 的静态图片可绘制对象屏幕截图，该屏幕截图会显示在 widget 选择器中。 我们建议您同时指定这两个属性，以便您的应用在旧平台上顺利回退。对于较新的平台（Android 15 及更高版本），您可以使用 `GlanceAppWidget.providePreview` 在 Kotlin 中定义实时生成的预览。请参阅生成的预览指南。
autoAdvanceViewId	指定由 widget 的宿主自动跳转的 widget 子视图的视图 ID。
widgetCategory	声明微件是否可以显示在主屏幕 (home_screen) 和/或锁定屏幕 (keyguard) 上。对于 Android 5.0 及更高版本，只有 home_screen 有效。
widgetFeatures	声明 widget 支持的功能。例如，如果 widget 的配置是可选的，请同时指定 configuration_optional 和 reconfigurable。

定义 GlanceAppWidget

1. 创建一个新类，该类从 GlanceAppWidget 扩展并替换 provideGlance 方法。您可以在此方法中加载渲染 widget 所需的数据：

   注意： provideGlance 在主线程上运行。如需在 provideGlance 中执行任何长时间运行的操作，请使用 withContext 切换到另一个线程。如需详细了解如何在主线程之外运行，请参阅使用协程确保主线程安全。

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. 在 GlanceAppWidgetReceiver 的 glanceAppWidget 中实例化该对象：

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

您现在已使用 Glance 配置 AppWidget。

使用 GlanceAppWidgetReceiver 类处理 widget 广播

GlanceAppWidgetReceiver 通过扩展底层 AppWidgetProvider 来协调 widget 广播和平台状态更新。当 widget 更新、删除、启用或停用时，它会接收平台事件，并将这些事件转换为 Compose 生命周期请求。

在清单中声明 widget

在 AndroidManifest.xml 文件中将 GlanceAppWidgetReceiver 类子类声明为广播接收器：

<receiver android:name="ExampleAppWidgetReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/my_app_widget_info" />
</receiver>

<receiver> 元素需要 android:name 属性，该属性用于指定接收器类。接收器必须接受 <intent-filter> 内的 ACTION_APPWIDGET_UPDATE 广播操作。

<meta-data> 元素必须将其名称标识为 android.appwidget.provider，并且 android:resource 属性必须指向您的 AppWidgetProviderInfo XML 元数据资源 (@xml/my_app_widget_info)。

实现 GlanceAppWidgetReceiver 类

在 Glance 中，您需要扩展 GlanceAppWidgetReceiver，而不是直接扩展 AppWidgetProvider。通过将接收器链接到 GlanceAppWidget 实例来实现此操作。GlanceAppWidgetReceiver 中提供的主要回调按如下方式运行：

• onUpdate()：由 Glance 自动替换，以执行合成更新。如果您手动替换 onUpdate，则必须调用 super.onUpdate，以允许 Glance 成功启动合成线程。
• onAppWidgetOptionsChanged()：在首次放置或调整微件大小时调用。Glance 读取选项会在后台捆绑项，以便您的布局根据运行时维度进行无缝调整。
• onDeleted(Context, IntArray)：每当用户删除特定 widget 实例时调用。
• onEnabled(Context)：当 widget 的第一个实例成功创建时触发。非常适合运行全局迁移。
• onDisabled(Context)：当提供程序的最后一个有效实例被移除时调用。
• onReceive(Context, Intent)：在特定回调方法之前拦截每个平台广播。您必须确保自己编写的任何自定义接收器逻辑都会调用 super.onReceive(context, intent)，并且绝不能自行调用 goAsync，因为 Glance 会自动异步路由工作。

警告： 由于接收器受到严格的 10 秒后台限制，因此长时间运行的操作绝不应在接收器回调中运行。如果您需要执行复杂的数据库查询或网络查找，请将任务委托给 WorkManager，并在完成后执行 GlanceAppWidget().update()。

接收 widget 广播 intent

从本质上讲，GlanceAppWidgetReceiver 会过滤并处理以下基础平台 widget 广播 intent：

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

创建界面

以下代码段演示了如何创建界面：

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

上述代码示例会执行以下操作：

• 在顶层 Column 中，各项会垂直放置，彼此紧挨。
• Column 会扩展其大小以匹配可用空间（通过 GlanceModifier），并将其内容与顶部对齐 (verticalAlignment) 并使其水平居中 (horizontalAlignment)。
• Column 的内容使用 lambda 定义。顺序很重要。
  • Column 中的第一个项是具有 12.dp 内边距的 Text 组件。
  • 第二个项是 Row，其中的项水平放置，一个接一个，并有两个水平居中的 Buttons (horizontalAlignment)。最终显示效果取决于可用空间。下图显示了该功能可能的外观：

图 1. 界面示例。

您可以更改对齐值或应用不同的修饰符值（例如内边距），以更改组件的位置和大小。如需查看每个类的组件、参数和可用修饰符的完整列表，请参阅参考文档。

实现圆角

Android 12 引入了系统参数，用于动态自定义应用微件的圆角半径：

• system_app_widget_background_radius：指定 widget 背景容器的角半径（绝不会大于 28 dp）。
• 内半径：为防止内容被剪裁，请根据系统背景轮廓计算内内容的比例半径：systemRadiusValue - widgetPadding

在 Glance 中，您可以使用 GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius) 在组合中动态应用圆角半径大小调整属性。

为了在搭载 Android 11（API 级别 30）或更低版本的设备上实现向后兼容性，请实现自定义属性和自定义主题资源回退：

• /values/attrs.xml

  <resources>
  <attr name="backgroundRadius" format="dimension" />
  </resources>
  

• /values/styles.xml

  <resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
  </resources>
  

• /values-31/styles.xml

  <resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
  </resources>
  

• /drawable/my_widget_background.xml

  <shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  </shape>