允许用户配置应用 widget

应用微件是可配置的。例如，时钟微件可以让用户配置要显示的时区。

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

声明配置 activity

在 Android 清单文件中将配置 activity 声明为常规 activity。应用 widget 宿主会通过 ACTION_APPWIDGET_CONFIGURE 操作启动它，因此 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 广播，这意味着系统不会在创建微件时调用 onUpdate() 方法。首次创建 widget 时，配置 activity 负责从 AppWidgetManager 请求更新。不过，系统会调用 onUpdate() 来执行后续更新，只在首次更新时不会调用它。

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

通过配置 activity 更新 widget

当微件使用配置 activity 时，由该 activity 负责在配置完成后更新微件。为此，您可以直接从 AppWidgetManager 请求更新。

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

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

   Kotlin

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

   Java

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }

2. 将 activity 结果设置为 RESULT_CANCELED。

   这样，如果用户在到达末尾之前退出该 activity，系统会通知应用微件托管应用配置已取消，因此托管应用不会添加 widget：

   Kotlin

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

   Java

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);

3. 根据用户的偏好配置微件。

4. 配置完成后，通过调用 getInstance(Context) 来获取 AppWidgetManager 的实例：

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

5. 通过调用 updateAppWidget(int,RemoteViews) 来使用 RemoteViews 布局更新 widget：

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)

   Java

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);

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

   Kotlin

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

   Java

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();

如需查看示例，请参阅 GitHub 上的 ListWidgetConfigureActivity.kt 示例类。

微件配置选项

默认情况下，应用 widget 宿主只会在用户将 widget 添加到其主屏幕后立即启动配置 activity 一次。但是，您可以指定相应选项，使用户能够重新配置现有的 widget 或通过提供默认 widget 配置跳过初始 widget 配置。

注意：这些选项仅从 Android 12（API 级别 31）开始提供。您可以为 Android 的早期版本指定这些值，但系统会忽略这些值并遵循默认行为。

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

如需允许用户重新配置现有 widget，请在 appwidget-provider 的 widgetFeatures 属性中指定 reconfigurable 标志。如需了解详情，请参阅有关声明 AppWidgetProviderInfo.xml 文件的指南。例如：

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

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

图 1. widget 重新配置按钮。

注意：reconfigurable 标志是在 Android 9（API 级别 28）中引入的，但直到 Android 12 才在启动器中得到广泛的支持。

使用微件的默认配置

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

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

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