改进 widget

本页面包含可选微件增强功能的详细信息。 从 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>

图 1.采用浅色主题的 widget。

。

<ph type="x-smartling-placeholder">

</ph>

图 2.采用深色主题的微件。

提示： 我们建议您遵循 Material 3 主题 确保设备之间一致性以及实现向后兼容的 Material Design 准则 兼容性。

动态配色的向后兼容性

动态配色仅适用于搭载 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>

图 3.默认情况下 出现在 3x3 区域中，但由于其 XML 布局，可以适应 3x1 区域。

为了显示准确的预览，您可以直接提供实际的 widget 具有默认值的布局，请执行以下操作：

• 正在为“TextView”设置“android:text="@string/my_widget_item_fake_1"” 元素。

  注意 ：使用 tools 标记设置的值，例如 tools:text="@string/my_wdiget_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 显示的选择器。

图 4. 显示 widget 的示例 widget 选择器 及其说明。

使用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>

警告： 请避免使用广播 trampoline。 从 Android 12 开始，应用仍可以从 如果广播接收器或服务是从微件点击的 PendingIntent。不过，新版应用 动画不用于通过广播接收器或服务启动的应用， 进而导致用户体验不佳。

您的应用可以在旧版 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);