本页包含从 Android 12(API 级别 31)开始提供的可选 widget 增强功能的详细信息。这些功能是可选的,但有助于实现和改善用户的 widget 体验。
使用动态配色
从 Android 12 开始,widget 可以为按钮、背景和其他组件使用设备主题颜色。这样可以在不同的 widget 之间提供更顺畅的过渡和一致性。
实现动态配色的方法有两种:
在根布局中使用系统的默认主题 (
@android:style/Theme.DeviceDefault.DayNight
)。使用 Material Components for Android 库中的 Material 3 主题 (
Theme.Material3.DynamicColors.DayNight
),该库从 Material Components for Android v1.6.0 开始提供。
在根布局中设置主题后,您可以使用根布局或其任何子项中的常用颜色属性来选取动态配色。
以下是一些您可以使用的颜色属性示例:
?attr/primary
?attr/primaryContainer
?attr/onPrimary
?attr/onPrimaryContainer
在下面的使用 Material 3 主题示例中,设备的主题颜色为“紫色”。强调色和 widget 背景会针对浅色模式和深色模式进行调整,如图 1 和图 2 所示。
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:background="?attr/colorPrimaryContainer"
android:theme="@style/Theme.Material3.DynamicColors.DayNight">
<ImageView
...
app:tint="?attr/colorPrimaryContainer"
android:src="@drawable/ic_partly_cloudy" />
<!-- Other widget content. -->
</LinearLayout>
![采用浅色模式主题的微件](https://developer.android.google.cn/static/images/appwidgets/example-lightmode.png?authuser=5&hl=th)
![采用深色模式主题的微件](https://developer.android.google.cn/static/images/appwidgets/example-darkmode.png?authuser=5&hl=th)
动态配色的向后兼容性
动态配色仅适用于搭载 Android 12 或更高版本的设备。如需为较低版本提供自定义主题,请使用自定义颜色和使用默认主题属性的新限定符 (values-v31
) 创建默认主题。
下面是一个使用 Material 3 主题的示例:
/values/styles.xml
<resources>
<style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
<!-- Override default colorBackground attribute with custom color. -->
<item name="android:colorBackground">@color/my_background_color</item>
<!-- Add other colors/attributes. -->
</style>
</resources>
/values-v31/styles.xml
<resources>
<!-- Do not override any color attribute. -->
<style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>
/layout/my_widget_layout.xml
<resources>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
...
android:background="?android:attr/colorBackground"
android:theme="@style/MyWidgetTheme" />
</resources>
启用语音支持
与应用有关的 Action 可让 Google 助理显示 widget 来响应相关的用户语音指令。通过将 widget 配置为响应内置 intent (BII),您的应用可以主动在 Google 助理界面(例如 Android 和 Android Auto)上显示 widget。用户可以选择将 Google 助理显示的 widget 固定到其启动器上,以鼓励未来的互动。
例如,您可以为锻炼应用配置锻炼摘要 widget,以执行触发 GET_EXERCISE_OBSERVATION
BII 的用户语音指令。当用户通过发出诸如“Hey Google,我本周在 ExampleApp 上跑了多少英里”之类的请求来触发此 BII 时,Google 助理会主动显示您的 widget。
有数十种 BII 涵盖多类用户互动,几乎所有 Android 应用都能增强其 widget 的语音功能。如需开始使用,请参阅将与应用有关的 Action 与 Android widget 集成。
改进应用的微件选择器体验
Android 12 可让您通过添加动态 widget 预览和 widget 说明来改善应用的 widget 选择器体验。
向微件选择器添加可缩放的微件预览
从 Android 12 开始,widget 选择器中显示的 widget 预览是可缩放的。您可以将其作为 XML 布局提供,并将其设置为 widget 的默认大小。以前,widget 预览是静态可绘制资源,因此在某些情况下,预览无法准确反映将 widget 添加到主屏幕时的显示效果。
如需实现可缩放的 widget 预览,请改为使用 appwidget-provider
元素的 previewLayout
属性提供 XML 布局:
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
我们建议使用与实际 widget 相同的布局,并具有真实的默认值或测试值。大多数应用都使用相同的 previewLayout
和 initialLayout
。如需了解如何创建准确的预览布局,请参阅本页中的以下部分。
我们建议您同时指定 previewLayout
和 previewImage
属性,以便用户在设备不支持 previewLayout
时,应用可以回退到使用 previewImage
。previewLayout
属性优先于 previewImage
属性。
构建准确预览的建议方法
如需实现可缩放的 widget 预览,请使用 appwidget-provider
元素的 previewLayout
属性提供 XML 布局:
<appwidget-provider
...
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
![显示 widget 预览的图片](https://developer.android.google.cn/static/images/appwidgets/todo-list-groceries.png?authuser=5&hl=th)
如需显示准确的预览,您可以通过完成以下步骤,直接为实际 widget 布局提供默认值:
为
TextView
元素设置android:text="@string/my_widget_item_fake_1"
。为
ImageView
组件设置默认或占位符图像或图标,例如android:src="@drawable/my_widget_icon"
。
如果没有默认值,预览可能会显示错误值或空值。此方法的一个重要优势是您可以提供本地化的预览内容。
如需了解实现包含 ListView
、GridView
或 StackView
的更复杂预览的推荐方法,请参阅构建包含动态项的准确预览,了解详情。
向后兼容可伸缩的 widget 预览
如需让 Android 11(API 级别 30)或更低版本的 widget 选择器显示 widget 的预览,请指定 previewImage
属性。
如果您更改了 widget 的外观,请更新预览图片。
为微件添加说明
从 Android 12 开始,请为要为您的 widget 显示的 widget 选择器提供说明。
![一张图片,其中显示了一个 widget 选择器,其中显示了一个 widget 及其说明](https://developer.android.google.cn/static/images/appwidgets/description.png?authuser=5&hl=th)
使用 <appwidget-provider>
元素的 description
属性为 widget 提供说明:
<appwidget-provider
android:description="@string/my_widget_description">
</appwidget-provider>
您可以在以前的 Android 版本上使用 descriptionRes
属性,但该属性会被 widget 选择器忽略。
实现更流畅的过渡
从 Android 12 开始,当用户从 widget 启动您的应用时,启动器可以提供更顺畅的过渡。
为了实现这种改进的过渡,请使用 @android:id/background
或 android.R.id.background
标识背景元素:
// Top-level layout of the widget.
<LinearLayout
android:id="@android:id/background">
</LinearLayout>
您的应用可以在以前的 Android 版本上使用 @android:id/background
,而不会中断,但会被忽略。
使用 RemoteViews 的运行时修改
从 Android 12 开始,您可以利用多种 RemoteViews
方法在运行时修改 RemoteViews
属性。如需查看所添加方法的完整列表,请参阅 RemoteViews
API 参考文档。
以下代码示例展示了如何使用其中的一些方法。
Kotlin
// Set the colors of a progress bar at runtime. remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList()) // Specify exact sizes for margins. remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)
Java
// Set the colors of a progress bar at runtime. remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList()); // Specify exact sizes for margins. remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);