本页面介绍了有关创建更高级 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
,然后从调用的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 时的注意事项
如果微件是从 BroadcastReceiver
(包括 AppWidgetProvider
)更新,请注意以下关于微件更新的时长和优先级的注意事项。
更新时长
一般来说,系统允许广播接收器(通常在应用的主线程中运行)最多运行 10 秒钟,之后就会将其视为无响应并触发应用无响应 (ANR) 错误。如果更新 widget 需要更长的时间,请考虑以下替代方案:
使用
WorkManager
安排任务。使用
goAsync
方法为接收器留出更多时间。这样,接收器就能执行 30 秒。
如需了解详情,请参阅安全注意事项和最佳做法。
更新的优先级
默认情况下,广播(包括使用 AppWidgetProvider.onUpdate
发出的广播)会作为后台进程运行。这意味着过载的系统资源可能会导致广播接收器的调用出现延迟。如需设置广播的优先级,请将其设为前台进程。
例如,当用户点按 widget 的特定部分时,将 Intent.FLAG_RECEIVER_FOREGROUND
标志添加到传递给 PendingIntent.getBroadcast
的 Intent
中。
构建包含动态项目的准确预览
![](https://developer.android.google.cn/static/images/appwidgets/missing-list.png?authuser=5&hl=ru)
本部分介绍了在具有集合视图的 widget(即使用 ListView
、GridView
或 StackView
的 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>
如需提供虚构列表项,您可以多次添加布局,但这会导致每个列表项相同。如需提供唯一的列表项,请按以下步骤操作:
为文本值创建一组属性:
<resources> <attr name="widgetTitle" format="string" /> <attr name="widgetContent" format="string" /> </resources>
使用以下属性来设置文本:
<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>
根据预览需要创建任意数量的样式。重新定义每种样式中的值:
<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>
在预览布局中对虚构项应用样式:
<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>