增强微件

本页面包含有关从 Android 12（API 级别 31）开始提供的可选微件增强功能的详细信息。这些功能是可选的，但实现起来很简单，并且可以改善用户的微件体验。

有关如何增强微件的其他方法，请参阅 Compose 指南增强您的微件。

使用动态配色

从 Android 12 开始，微件可以使用设备主题颜色来设置按钮、背景和其他组件。这提供了更平滑的过渡效果，并确保了不同微件之间的一致性。

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

在根布局中使用系统的默认主题（@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 主题的示例中，设备的主题颜色为“紫罗兰色”。强调色和微件背景会根据浅色和深色模式进行调整，如图 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>

Widget in light mode theme — **图 1.** 浅色主题下的微件。

Widgets in dark mode theme — **图 2.** 深色主题下的微件。

动态配色的向后兼容性

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

启用语音支持

应用操作 (App Actions) 让 Google 助理能够响应相关的用户语音指令来显示微件。通过配置您的微件以响应内置意图 (BII)，您的应用可以主动在 Android 和 Android Auto 等助理界面上显示微件。用户可以选择将助理显示的微件固定到其启动器上，从而促进后续互动。

例如，您可以配置健身应用的锻炼摘要微件，以满足触发 GET_EXERCISE_OBSERVATION BII 的用户语音指令。当用户通过说出诸如“Hey Google，我在 ExampleApp 上这周跑了多少英里？”之类的请求来触发此 BII 时，助理会主动显示您的微件。

有数十种涵盖多个用户交互类别的 BII，几乎可以让任何 Android 应用为其微件增强语音功能。要开始使用，请参阅将应用操作集成到 Android 微件中。

启用更平滑的过渡

从 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 参考，获取已添加方法的完整列表。

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

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