本页面包含可选微件增强功能的详细信息。 从 Android 12(API 级别 31)开始。这些功能是可选的 易于实施和改进用户微件体验
使用动态配色
从 Android 12 开始,微件可以使用设备主题颜色 用于按钮、背景和其他组件。这会使视频画面更流畅 以及在不同微件间的一致性和一致性
实现动态配色的方法有两种:
使用系统的默认主题 (
@android:style/Theme.DeviceDefault.DayNight
)。使用 Material 3 主题 (
Theme.Material3.DynamicColors.DayNight
) 用于 Android 设备 库开始,从适用于 Android 的 Material 组件开始提供 v1.6.0。
在根布局中设置主题后,您可以在 根或其任何子元素来选择动态配色。
以下是您可以使用的颜色属性的一些示例:
?attr/primary
?attr/primaryContainer
?attr/onPrimary
?attr/onPrimaryContainer
在使用 Material 3 主题的以下示例中,设备的主题颜色为 “紫色”。强调色和微件背景可适应浅色和深色 如图 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>
<ph type="x-smartling-placeholder">![采用浅色模式主题的微件](https://developer.android.google.cn/static/images/appwidgets/example-lightmode.png?authuser=7&hl=lt)
![采用深色模式主题的微件](https://developer.android.google.cn/static/images/appwidgets/example-darkmode.png?authuser=7&hl=lt)
动态配色的向后兼容性
动态配色仅适用于搭载 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 助理 显示微件以响应相关的用户语音指令。通过配置 微件响应内置 intent (BII)、您的 应用可以主动在 Google 助理界面(例如 Android 和 Android Auto。用户可以选择固定 显示这些微件 启动器,以鼓励未来参与互动。
例如,您可以为锻炼应用配置“锻炼摘要”微件
执行触发
GET_EXERCISE_OBSERVATION
BII。当用户通过以下方式触发此 BII 时,Google 助理会主动显示您的 widget
例如“Hey Google,我这周跑了多少英里”
ExampleApp?”
有数十个 BII,涵盖多个类别的用户互动, 让几乎所有 Android 应用都能增强其语音微件。首先, 请参阅将与应用有关的 Action 与 Android widget 集成。
改进应用的微件选择器体验
在 Android 12 中,您可以改进 widget 选择器的体验 通过添加动态微件预览和微件说明来调整您的应用。
向微件选择器添加可缩放的微件预览
从 Android 12 开始,微件预览会显示在 微件选择器是可缩放的。您可以以 XML 布局的形式提供它,并将布局设置为 默认大小。以前,widget 预览是 某些情况下会导致预览无法准确反映 系统会将它们添加到主屏幕
如需实现可缩放的 widget 预览,请使用
previewLayout
属性来提供 XML 布局:appwidget-provider
<appwidget-provider
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
我们建议使用与实际 widget 相同的布局,并采用真实的默认值
或测试值。大多数应用使用相同的 previewLayout
和 initialLayout
。对于
有关创建准确预览布局的指南,请参阅以下部分
页面。
我们建议您同时指定 previewLayout
和 previewImage
属性,
以便在用户设备处于登录状态时,您的应用可以回退到使用 previewImage
不支持 previewLayout
。previewLayout
属性优先
previewImage
属性。
构建准确预览的推荐方法
如需实现可缩放的 widget 预览,请使用previewLayout
appwidget-provider
元素来提供 XML 布局:
<appwidget-provider
...
android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>
<ph type="x-smartling-placeholder">![显示 widget 预览的图片](https://developer.android.google.cn/static/images/appwidgets/todo-list-groceries.png?authuser=7&hl=lt)
为了显示准确的预览,您可以直接提供实际的 widget 具有默认值的布局,请执行以下操作:
正在为“
TextView
”设置“android:text="@string/my_widget_item_fake_1"
” 元素。设置默认或占位图片或图标,例如
android:src="@drawable/my_widget_icon"
,适用于ImageView
组件。
如果没有默认值,预览可能会显示不正确的值或空值。一个 这种方法的一大好处是 内容。
如需了解包含 ListView
的更复杂预览的推荐方法,
GridView
或 StackView
,请参阅构建包含动态效果的准确预览
items。
向后兼容可缩放的 widget 预览
若要让 Android 11(API 级别 30)或更低版本上的微件选择器显示
widget,请指定 previewImage
属性。
如果您更改微件的外观,请更新预览图片。
为微件添加说明
从 Android 12 开始,为 widget 提供说明 为您的 widget 显示的选择器。
![一张显示了 widget 选择器的图片,其中显示了一个 widget 及其说明](https://developer.android.google.cn/static/images/appwidgets/description.png?authuser=7&hl=lt)
使用description
<appwidget-provider>
元素:
<appwidget-provider
android:description="@string/my_widget_description">
</appwidget-provider>
您可以使用
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);