允许用户配置应用 widget

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

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

声明配置 activity

在 Android 清单文件中将配置 activity 声明为正常 activity。应用微件托管应用会使用 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() 方法。首次创建微件时，由配置 activity 负责从 AppWidgetManager 请求更新。不过，系统会调用 onUpdate() 来执行后续更新，只在首次更新时不会调用它。

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

通过配置 activity 更新微件

当微件使用配置 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 示例类。

微件配置选项

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

注意： 这些选项仅从 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. “微件”重新配置按钮。

注意： 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>