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

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

要允许用户重新配置现有的微件，请指定 reconfigurable 标记（位于 widgetFeatures appwidget-provider 的属性。请参阅有关声明 AppWidgetProviderInfo.xml 文件了解详情 信息。例如：

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

用户可通过触摸和按住微件并点按 重新配置按钮，该按钮标有 图 1 中的 1。

。

使用微件的默认配置

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

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

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