创建高级 widget

本页面介绍了有关创建更高级 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。在此期间,旧数据会显示在该微件中。您可以使用此方法安全地同步执行开销大的任务。

    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 属性提供的值定期更新。微件可以更新以响应用户互动和/或广播更新。

定期更新

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

updatePeriodMillis”不支持短于 30 分钟的值。但是,如果要停用定期更新,您可以指定 0。

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

为响应用户互动而更新

下面是一些根据用户互动更新 widget 的推荐方法:

  • 通过应用的 activity:直接调用 AppWidgetManager.updateAppWidget 以响应用户互动(例如用户点按)。

  • 通过远程交互(例如通知或应用 widget):构建 PendingIntent,然后从调用的 ActivityBroadcastService 更新 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 时的注意事项

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

更新时长

一般来说,系统允许广播接收器(通常在应用的主线程中运行)最多运行 10 秒钟,之后就会将其视为无响应并触发应用无响应 (ANR) 错误。如果更新 widget 需要更长的时间,请考虑以下替代方案:

  • 使用 WorkManager 安排任务。

  • 使用 goAsync 方法为接收器留出更多时间。这样,接收器就能执行 30 秒。

如需了解详情,请参阅安全注意事项和最佳做法

更新的优先级

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

例如,当用户点按 widget 的特定部分时,将 Intent.FLAG_RECEIVER_FOREGROUND 标志添加到传递给 PendingIntent.getBroadcastIntent 中。

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

图 1 :不显示任何列表项的 widget 预览。

本部分介绍了在具有集合视图的 widget(即使用 ListViewGridViewStackView 的 widget)的 widget 预览中显示多个项的建议方法。

如果您的 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>