允许用户配置应用 widget

设计微件时，应让用户能够配置特定特征。例如，时钟微件可让用户配置要显示的时区。

如果您想让用户配置微件的设置，请创建一个微件 配置 Activity。此 activity 由 应用微件宿主在创建微件时或稍后自动启动，具体取决于您指定的 配置选项。

声明配置 activity

在 Android 清单文件中将配置 activity 声明为普通 activity。应用微件宿主使用 ACTION_APPWIDGET_CONFIGURE 操作启动该 activity，因此该 activity 需要接受此 intent。例如：

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

使用 android:configure 属性在 AppWidgetProviderInfo.xml 文件中声明该 activity。如需详细了解如何声明此文件，请参阅此处。下面展示了如何声明配置 activity 的示例：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

该 activity 是使用完全限定的命名空间声明的，因为启动器会从您的软件包范围之外引用它。

这就是启动配置 activity 所需的全部内容。接下来，您需要实现实际 activity。

实现配置 activity

实现该 activity 时，需要记住以下两个要点：

• 应用微件宿主调用配置 activity，并且配置 activity 必须始终返回结果。结果必须包含由启动该 activity 的 intent 传递的应用微件 ID，该 ID 在 intent extra 中保存为 EXTRA_APPWIDGET_ID。
  • 启动配置 activity 时，系统不会发送 ACTION_APPWIDGET_UPDATE 广播 ，这意味着在创建微件时，系统最初不会调用 微件更新。首次创建微件时，由配置 activity 负责从 GlanceAppWidget 请求更新。 不过，后续周期会自动触发更新。

有关如何从配置返回结果并更新 Glance 微件的示例，请参阅下一部分中的代码段。

通过配置 activity 更新微件

当微件使用配置 activity 时，由该 activity 负责在配置完成后更新微件。您可以通过直接从 GlanceAppWidget 实例触发手动更新来实现此目的。

下面简要说明了正确更新微件并关闭配置 activity 的过程：

1. 从启动该 activity 的 intent 获取应用微件 ID：

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. 将 activity 结果设置为 RESULT_CANCELED。

   这样，如果用户在到达末尾之前退出该 activity，系统就会通知应用微件宿主配置已取消，并且宿主不会添加微件：

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. 根据用户的偏好设置配置微件，例如将选择写入持久性数据存储区或本地数据库。

4. 配置完成后，检索与平台微件 ID 对应的 GlanceId：

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. 通过对 GlanceAppWidget 实例调用 update suspend 函数来更新微件内容：

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. 创建返回 intent，为其设置 activity 结果，然后结束该 activity：

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

微件配置选项

默认情况下，应用微件宿主仅在用户将微件添加到其主屏幕后立即启动配置 activity 一次。不过，您可以指定一些选项，让用户能够重新配置现有微件，或者通过提供默认微件配置来跳过初始微件配置。

允许用户重新配置已放置的微件

如需让用户重新配置现有微件，请在 widgetFeatures 的 reconfigurable 属性中指定 appwidget-provider 标志。例如：

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

用户可以通过触摸并按住微件，然后点按重新配置 按钮（在图 1 中标记为 1）来重新配置微件。

使用微件的默认配置

您可以让用户跳过初始配置步骤，从而提供更顺畅的微件体验。为此，请在 widgetFeatures 字段中同时指定 configuration_optional 和 reconfigurable 标志。这样会在用户添加微件后绕过启动配置 activity。如前所述，用户以后仍可重新配置微件 。例如，时钟微件可以绕过初始配置，并在默认情况下显示设备时区。

下面展示了如何将配置 activity 标记为既可重新配置又是可选的示例：

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>