允许用户配置应用 widget

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

如果您想允许用户配置微件的设置，请创建微件 配置 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>

使用AppWidgetProviderInfo.xml android:configure 属性。详细了解如何声明此文件。这里的示例 如何声明配置 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 时需要记住两个要点：

• 应用 widget 宿主调用配置 activity，而配置 activity 必须始终返回结果。结果必须包含由启动该 activity 的 intent 传递的应用微件 ID（在 intent extra 中保存为 EXTRA_APPWIDGET_ID）。
• 系统不会发送 ACTION_APPWIDGET_UPDATE 并在配置 activity 启动时进行广播，这意味着它不会 在创建 widget 时调用 onUpdate() 方法。 由配置 activity 负责从 AppWidgetManager。不过，系统会调用 onUpdate() 来执行后续更新，只在首次更新时不会调用它。

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

从配置 activity 更新 widget

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

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

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

   KotlinJava

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

   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 宿主配置已取消，并 主持人未添加该微件：

   KotlinJava

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

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

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

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

   KotlinJava

   val appWidgetManager = AppWidgetManager.getInstance(context)

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

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

   KotlinJava

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

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

6. 创建返回 intent，使用 activity 结果对其进行设置，然后 完成 activity：

   KotlinJava

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

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

请参阅 ListWidgetConfigureActivity.kt 获取示例。

微件配置选项

默认情况下，应用微件宿主只会在用户将微件添加到其主屏幕后立即启动配置 activity 一次。不过，您 可以指定相关选项，使用户能够重新配置现有的微件或 通过提供默认的 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. “微件”重新配置按钮。

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

使用微件的默认配置

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

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

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