创建高级 widget

尝试使用 Compose 方式

Jetpack Compose 是推荐用于 Android 的界面工具包。了解如何使用 Compose 风格的 API 构建 widget。

Jetpack Glance →

本页介绍了创建更高级的 widget 以提供更优质的用户体验的推荐做法。

用于更新 widget 内容的优化

更新 widget 内容的计算开销可能很大。为了节省电池消耗，请优化更新类型、频率和时间。

微件更新的类型

您可以通过以下三种方式更新 widget：完全更新、部分更新，以及（对于集合 widget）数据刷新。每种方法都有不同的计算成本和影响。

下文介绍了每种更新类型，并提供了每种类型的代码段。

• 完全更新：调用 AppWidgetManager.updateAppWidget(int, android.widget.RemoteViews) 以完全更新 widget。这会将之前提供的 RemoteViews 替换为新的 RemoteViews。这是计算成本最高的更新。

  Kotlin

  val appWidgetManager = AppWidgetManager.getInstance(context)
  val remoteViews = RemoteViews(context.getPackageName(), R.layout.widgetlayout).also {
  setTextViewText(R.id.textview_widget_layout1, "Updated text1")
  setTextViewText(R.id.textview_widget_layout2, "Updated text2")
  }
  appWidgetManager.updateAppWidget(appWidgetId, remoteViews)

  Java

  AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
  RemoteViews remoteViews = new RemoteViews(context.getPackageName(), R.layout.widgetlayout);
  remoteViews.setTextViewText(R.id.textview_widget_layout1, "Updated text1");
  remoteViews.setTextViewText(R.id.textview_widget_layout2, "Updated text2");
  appWidgetManager.updateAppWidget(appWidgetId, remoteViews);

• 部分更新：调用 AppWidgetManager.partiallyUpdateAppWidget 以更新 widget 的部分内容。此操作会将新的 RemoteViews 与之前提供的 RemoteViews 合并。如果 widget 未通过 updateAppWidget(int[], RemoteViews) 至少接收一次完整更新，则忽略此方法。

  Kotlin

  val appWidgetManager = AppWidgetManager.getInstance(context)
  val remoteViews = RemoteViews(context.getPackageName(), R.layout.widgetlayout).also {
  setTextViewText(R.id.textview_widget_layout, "Updated text")
  }
  appWidgetManager.partiallyUpdateAppWidget(appWidgetId, remoteViews)

  Java

  AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
  RemoteViews remoteViews = new RemoteViews(context.getPackageName(), R.layout.widgetlayout);
  remoteViews.setTextViewText(R.id.textview_widget_layout, "Updated text");
  appWidgetManager.partiallyUpdateAppWidget(appWidgetId, remoteViews);

• 集合数据刷新：调用 AppWidgetManager.notifyAppWidgetViewDataChanged 以使 widget 中集合视图的数据失效。这会触发 RemoteViewsFactory.onDataSetChanged。在此期间，widget 中会显示旧数据。您可以使用此方法安全地同步执行耗时任务。

  Kotlin

  val appWidgetManager = AppWidgetManager.getInstance(context)
  appWidgetManager.notifyAppWidgetViewDataChanged(appWidgetId, R.id.widget_listview)

  Java

  AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
  appWidgetManager.notifyAppWidgetViewDataChanged(appWidgetId, R.id.widget_listview);

只要应用具有与相应 AppWidgetProvider 类相同的 UID，您就可以从应用中的任何位置调用这些方法。

确定更新 widget 的频率

系统会根据为 updatePeriodMillis 属性提供的值定期更新 widget。该 widget 可以响应用户互动、广播更新，或同时执行这两项操作。

定期更新

您可以在 appwidget-provider XML 中为 AppWidgetProviderInfo.updatePeriodMillis 指定一个值，以控制定期更新的频率。每次更新都会触发 AppWidgetProvider.onUpdate() 方法，您可以在其中放置用于更新 widget 的代码。不过，如果您的 widget 需要异步加载数据或更新时间超过 10 秒，请考虑下一部分中介绍的广播接收器更新替代方案，因为 10 秒后，系统会将 BroadcastReceiver 视为无响应。

updatePeriodMillis 不支持小于 30 分钟的值。不过，如果您想停用定期更新，可以指定 0。

您可以让用户在配置中调整更新频率。例如，他们可能希望股票行情自动收录器每 15 分钟更新一次，或者一天只更新 4 次。在这种情况下，请将 updatePeriodMillis 设置为 0，并改用 WorkManager。

注意： 使用 WorkManager 处理重复性任务是一个不错的选择，但同样会受到电源限制。如需了解详情，请参阅应用待机模式分桶。

根据用户互动进行更新

以下是一些建议，可帮助您根据用户互动更新 widget：

• 从应用的 activity 中：直接调用 AppWidgetManager.updateAppWidget 以响应用户互动（例如用户点按）。

• 通过远程互动（例如通知或应用 widget）：构建 PendingIntent，然后从调用的 Activity、Broadcast 或 Service 更新 widget。您可以自行选择优先级。例如，如果您为 PendingIntent 选择 Broadcast，则可以选择前台广播来为 BroadcastReceiver 提供优先级。

根据广播事件进行更新

需要 widget 更新的广播事件的一个示例是用户拍照时。在这种情况下，您希望在检测到新照片时更新 widget。

您可以使用 JobScheduler 调度作业，并使用 JobInfo.Builder.addTriggerContentUri 方法指定广播作为触发器。

您还可以为广播注册 BroadcastReceiver，例如监听 ACTION_LOCALE_CHANGED。不过，由于这会消耗设备资源，因此请谨慎使用此功能，并且仅监听特定的广播。随着 Android 7.0（API 级别 24）和 Android 8.0（API 级别 26）中广播限制的引入，应用无法再在其清单中注册隐式广播，但存在一些例外情况。

从 BroadcastReceiver 更新 widget 时的注意事项

如果 widget 是从 BroadcastReceiver（包括 AppWidgetProvider）更新的，请注意以下有关 widget 更新时长和优先级的注意事项。

更新时长

一般来说，系统会允许广播接收器（通常在应用的主线程中运行）运行长达 10 秒，然后才会认为它们无响应并触发应用无响应 (ANR) 错误。为避免在处理广播时阻塞主线程，请使用 goAsync 方法。如果更新 widget 需要更长时间，请考虑使用 WorkManager 安排任务。

Caution: Any work you do here blocks further broadcasts until it completes,
so it can slow the receiving of later events.

如需了解详情，请参阅安全注意事项和最佳实践。

更新的优先级

默认情况下，广播（包括使用 AppWidgetProvider.onUpdate 进行的广播）作为后台进程运行。这意味着，过载的系统资源可能会导致广播接收器的调用延迟。如需优先处理广播，请将其设为前台进程。

例如，当用户点按 widget 的某个部分时，向传递给 PendingIntent.getBroadcast 的 Intent 添加 Intent.FLAG_RECEIVER_FOREGROUND 标志。