增强您的 widget

此页面包含从 Android 12（API 级别 31）开始可用的可选小部件增强功能的详细信息。这些功能是可选的，但它们易于实施并改善用户的 widget 体验。

使用动态颜色

从 Android 12 开始，小部件可以使用设备主题颜色为按钮、背景和其他组件着色。这提供了更平滑的过渡并在不同小部件之间保持一致性。

有两种方法可以实现动态颜色

• 在根布局中使用系统的默认主题（@android:style/Theme.DeviceDefault.DayNight）。

• 从 Android 版 Material Components 库（从 Android 版 Material Components v1.6.0 开始提供）中使用 Material 3 主题（Theme.Material3.DynamicColors.DayNight）。

在根布局中设置主题后，您可以在根或其任何子元素中使用常用颜色属性来获取动态颜色。

以下是一些您可以使用的颜色属性示例

• ?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>

动态颜色的向后兼容性

动态颜色仅在运行 Android 12 或更高版本的设备上可用。要为较低版本提供自定义主题，请使用默认主题属性创建一个包含自定义颜色的默认主题和一个新的限定符（values-v31）。

以下是如何使用 Material 3 主题的示例

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

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

启用语音支持

应用操作 允许 Google 助理根据相关的用户语音命令显示小部件。通过将您的 widget 配置为响应 内置意图 (BII)，您的应用可以主动地在助理界面（如 Android 和 Android Auto）上显示小部件。用户可以选择 将助理显示的小部件固定 到他们的启动器，从而鼓励未来的参与。

例如，您可以将锻炼应用的锻炼摘要小部件配置为满足触发 GET_EXERCISE_OBSERVATION BII 的用户语音命令。当用户通过发出类似“嘿 Google，我在 ExampleApp 上本周跑了多少英里？”之类的请求触发此 BII 时，助理会主动显示您的 widget。

有数十个 BII 涵盖了多个用户交互类别，几乎所有 Android 应用都可以增强其小部件以实现语音交互。要开始使用，请参阅 将应用操作与 Android 小部件集成。

改进您的应用的小部件选择器体验

Android 12 允许您通过添加动态小部件预览和小部件描述来改进应用的小部件选择器体验。

向小部件选择器添加可缩放的小部件预览

从 Android 12 开始，在小部件选择器中显示的小部件预览是可缩放的。您将其提供为设置为小部件默认大小的 XML 布局。以前，小部件预览是静态的可绘制资源，在某些情况下会导致预览无法准确反映小部件添加到主屏幕后的显示方式。

要实现可缩放的小部件预览，请使用 appwidget-provider 元素的 previewLayout 属性提供 XML 布局，而不是

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

我们建议使用与实际小部件相同的布局，并使用逼真的默认值或测试值。大多数应用使用相同的 previewLayout 和 initialLayout。有关创建准确预览布局的指南，请参阅此页面中的下一部分。

我们建议同时指定 previewLayout 和 previewImage 属性，以便您的应用如果用户的设备不支持 previewLayout，则可以回退到使用 previewImage。 previewLayout 属性优先于 previewImage 属性。

构建准确预览的推荐方法

要实现可缩放的小部件预览，请使用 appwidget-provider 元素的 previewLayout 属性提供 XML 布局

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

要显示准确的预览，您可以通过完成以下步骤直接提供实际的小部件布局以及默认值

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

• 设置默认或占位符图像或图标，例如 android:src="@drawable/my_widget_icon"，用于 ImageView 组件。

如果没有默认值，预览可能会显示不正确或为空的值。此方法的一个重要好处是您可以提供本地化的预览内容。

对于包含 ListView、GridView 或 StackView 的更复杂预览的推荐方法，请参阅 构建包含动态项的准确预览 以获取详细信息。

可缩放小部件预览的向后兼容性

要让 Android 11（API 级别 30）或更低版本的小部件选择器显示您的小部件预览，请指定 previewImage 属性。

如果更改了小部件的外观，请更新预览图像。

为您的 widget 添加说明

从 Android 12 开始，为小部件选择器提供您的小部件的说明。

使用 <appwidget-provider> 元素的 description 属性为您的 widget 提供说明

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

您可以在 Android 的早期版本上使用 descriptionRes 属性，但小部件选择器会忽略它。

启用更平滑的过渡

从 Android 12 开始，当用户从小部件启动您的应用时，启动器会提供更平滑的过渡。

要启用此改进的过渡，请使用 @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 参考。

以下代码示例展示了如何使用其中一些方法。

// 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)

// 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);