允许用户配置应用 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>

使用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）。
• 启动配置 activity 时，系统不会发送 ACTION_APPWIDGET_UPDATE 广播，这意味着系统不会在创建微件时调用 onUpdate() 方法。首次创建微件时，由配置 activity 负责从 AppWidgetManager 请求更新。不过， 系统会针对后续更新调用 onUpdate()，只会跳过 。

有关如何返回 结果，并更新 widget。

从配置 activity 更新 widget

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

下面概要列出了正确更新该微件并关闭 配置活动：

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. 根据用户的偏好设置配置 widget。

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

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. 使用 RemoteViews 布局（通过调用 updateAppWidget(int,RemoteViews):

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

请参阅 ListWidgetConfigureActivity.kt 获取示例。

微件配置选项

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

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

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

要允许用户重新配置现有的微件，请指定 reconfigurable 标记（位于 widgetFeatures appwidget-provider 的属性。请参阅有关声明 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>