允许用户配置应用 widget

设计微件，以便用户可以配置特定特征。例如，时钟 widget 可以让用户配置要显示哪个时区。

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

声明配置 activity

在 Android 清单文件中将配置 activity 声明为常规 activity。应用 widget 宿主会使用 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（在 intent extra 中保存为 EXTRA_APPWIDGET_ID）。
  • 当配置 activity 启动时，系统不会发送 ACTION_APPWIDGET_UPDATE 广播，这意味着在创建 widget 时，系统最初不会调用您的 widget 更新。配置 activity 负责在首次创建 widget 时向 GlanceAppWidget 请求更新。不过，在后续周期中，系统会自动触发更新。

如需查看如何从配置返回结果并更新 Glance widget 的示例，请参阅下一部分中的代码段。

通过配置 activity 更新 widget

当 widget 使用配置 activity 时，该 activity 负责在配置完成后更新 widget。为此，您可以直接从 GlanceAppWidget 实例触发手动更新。

下面简要介绍了正确更新 widget 并关闭配置 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 末尾之前退出，系统会通知应用 widget 宿主配置已取消，并且宿主不会添加 widget：

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

3. 根据用户偏好设置配置 widget，例如将选择项写入持久性 DataStore 或本地数据库。

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

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

5. 通过对 GlanceAppWidget 实例调用 update 挂起函数来更新 widget 内容：

   // 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()
   

widget 配置选项

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

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

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

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

用户可以重新配置 widget，方法是触摸并按住该 widget，然后点按图 1 中标记为 1 的重新配置按钮。

使用微件的默认配置

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

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

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