创建高级 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 以更新微件的部分内容。这会将新的 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);

您可以从应用中的任何位置调用这些方法，前提是应用的 UID 与相应的 AppWidgetProvider 类相同。

确定微件更新的频率

widget 会根据为 updatePeriodMillis 属性提供的值定期更新。该 widget 可以更新来响应用户互动和/或广播更新。

定期更新

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

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

您可以允许用户在配置中调整更新频率。例如，他们可能希望股票报价每 15 分钟更新一次或每天只更新一次。在这种情况下，请将 updatePeriodMillis 设置为 0，并改用 WorkManager。

更新以响应用户互动

下面是根据用户互动更新微件的几种推荐方法：

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

  • 通过远程互动（例如通知或应用微件）：构建 PendingIntent，然后通过调用的 Activity、Broadcast 或 Service 更新微件。您可以自行选择优先级。例如，如果您为 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 时的注意事项

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

更新时长

通常，系统会让广播接收器（通常在应用的主线程中运行）最多运行 10 秒钟，然后才会将其视为无响应并触发应用无响应 (ANR) 错误。如果更新 widget 需要更长时间，请考虑以下替代方案：

  • 使用 WorkManager 安排任务。

  • 使用 goAsync 方法为接收器提供更多时间。这样一来，接收器便可执行 30 秒。

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

更新的优先级

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

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

构建包含动态项的准确预览

图 1 ：不显示列表项的微件预览。

本部分介绍了针对具有集合视图（即使用 ListView、GridView 或 StackView 的 widget）的 widget 在 widget 预览中显示多个项的推荐方法。

如果您的微件使用其中一种视图，通过直接提供实际的微件布局创建可缩放的预览会降低微件预览不显示任何项时的体验。之所以会出现这种情况，是因为集合视图数据是在运行时动态设置的，并且看起来与图 1 中显示的图片类似。

为了让包含集合视图的 widget 的预览在 widget 选择器中正确显示，我们建议您维护一个单独的布局文件，仅用于预览。此单独的布局文件包含实际的 widget 布局和包含虚构项的占位符集合视图。例如，您可以通过提供包含多个虚构列表项的占位符 LinearLayout 来模拟 ListView。

为了说明 ListView 的示例，我们先创建一个单独的布局文件：

// res/layout/widget_preview.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:background="@drawable/widget_background"
   android:orientation="vertical">

    // Include the actual widget layout that contains ListView.
    <include
        layout="@layout/widget_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    // The number of fake items you include depends on the values you provide
    // for minHeight or targetCellHeight in the AppWidgetProviderInfo
    // definition.

    <TextView android:text="@string/fake_item1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

    <TextView android:text="@string/fake_item2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

</LinearLayout>

提供 AppWidgetProviderInfo 元数据的 previewLayout 属性时，请指定预览布局文件。您仍然需要为 initialLayout 属性指定实际的 widget 布局，并在运行时构建 RemoteViews 时使用实际的 widget 布局。

<appwidget-provider
    previewLayout="@layout/widget_previe"
    initialLayout="@layout/widget_view" />

复杂列表项

上一部分中的示例提供了虚构的列表项，因为列表项是 TextView 对象。如果项是复杂的布局，则提供虚构项的操作可能会更复杂。

假设在 widget_list_item.xml 中定义了一个列表项，该列表项由两个 TextView 对象组成：

<LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_title" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_content" />
</LinearLayout>

如需提供虚构列表项，您可以多次添加该布局，但这会导致每个列表项都相同。如需提供唯一的列表项，请按以下步骤操作：

  1. 为文本值创建一组属性：

    <resources>
    <attr name="widgetTitle" format="string" />
    <attr name="widgetContent" format="string" />
</resources>

  2. 使用以下属性设置文本：

    <LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="?widgetTitle" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="?widgetContent" />
</LinearLayout>

  3. 根据预览的需要创建任意数量的样式。重新定义每种样式的值：

    <resources>

    <style name="Theme.Widget.ListItem">
        <item name="widgetTitle"></item>
        <item name="widgetContent"></item>
    </style>
    <style name="Theme.Widget.ListItem.Preview1">
        <item name="widgetTitle">Fake Title 1</item>
        <item name="widgetContent">Fake content 1</item>
    </style>
    <style name="Theme.Widget.ListItem.Preview2">
        <item name="widgetTitle">Fake title 2</item>
        <item name="widgetContent">Fake content 2</item>
    </style>

</resources>

  4. 在预览布局中的虚构项上应用样式：

    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content" ...>

    <include layout="@layout/widget_view" ... />

    <include layout="@layout/widget_list_item"
        android:theme="@style/Theme.Widget.ListItem.Preview1" />

    <include layout="@layout/widget_list_item"
        android:theme="@style/Theme.Widget.ListItem.Preview2" />

</LinearLayout>