允许用户配置应用小组件

应用小组件可以配置。例如，时钟小组件可以允许用户配置要显示的区域。

如果您想允许用户配置小组件的设置，请创建一个小组件配置 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 extras 中作为 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，系统会通知应用小组件主机配置已取消，主机不会添加该小组件。

    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 布局更新小组件

    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 一次。但是，您可以指定选项，允许用户重新配置现有小组件，或通过提供默认小组件配置跳过初始小组件配置。

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

要让用户重新配置现有小组件，请在 appwidget-provider 的 widgetFeatures 属性中指定 reconfigurable 标志。有关声明 AppWidgetProviderInfo.xml 文件的更多信息，请参阅指南。例如：

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

用户可以通过长按小组件并点击 重新配置 按钮来重新配置其小组件，图 1 中标记为 1。

Button appears in bottom-right corner
图 1. 小组件 重新配置 按钮。

使用小组件的默认配置

您可以允许用户跳过初始配置步骤，从而提供更流畅的小组件体验。为此，请在 widgetFeatures 字段中同时指定 configuration_optional 和 reconfigurable 标志。这会在用户添加小组件后绕过启动配置 activity。如前所述，用户之后仍然可以重新配置小组件。例如，时钟小组件可以绕过初始配置，默认显示设备时区。

以下是标记配置 activity 为可重新配置且可选的示例：

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