允许用户配置应用 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 中） extras： EXTRA_APPWIDGET_ID。
• 系统不会发送 ACTION_APPWIDGET_UPDATE 并在配置 activity 启动时进行广播，这意味着它不会 在创建 widget 时调用 onUpdate() 方法。 由配置 activity 负责从 AppWidgetManager。不过， 系统会针对后续更新调用 onUpdate()，只会跳过 。

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

从配置 activity 更新 widget

当 widget 使用配置 activity 时，负责 在配置完成后更新 widget 的 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 获取示例。

widget 配置选项

默认情况下，应用 widget 宿主仅启动一次配置 activity， 。不过，您 可以指定相关选项，使用户能够重新配置现有的微件或 通过提供默认的 widget 配置来跳过初始 widget 配置。

注意 ：这些选项从 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 才得到广泛支持。

使用微件的默认配置

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

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

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