強化小工具

本頁詳細說明 Android 12 (API 級別 31) 起開始提供的選用小工具強化功能。這些功能為選用項目，但可直接實作及改善使用者的小工具體驗。

使用動態色彩

自 Android 12 起，小工具可針對按鈕、背景和其他元件使用裝置主題顏色。如此一來，不同小工具之間的轉換和一致性就能更順暢。

有兩種方法可以呈現動態色彩：

• 在根版面配置中使用系統的預設主題 (@android:style/Theme.DeviceDefault.DayNight)。

• 使用 Android Material 元件程式庫中的 Material 3 主題 (Theme.Material3.DynamicColors.DayNight)，自 Android 1.6.0 版 Material 元件開始提供。

在根版面配置中設定主題後，您就可以在根層級或其子項中使用通用的顏色屬性來挑選動態色彩。

以下是一些可以使用的顏色屬性範例：

• ?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 助理根據相關使用者語音指令顯示小工具。只要將小工具設為回應內建意圖 (BII)，應用程式就能主動在 Android 和 Android Auto 等 Google 助理介面上顯示小工具。使用者可以選擇在啟動器中固定 Google 助理顯示的小工具，鼓勵日後與 Google 助理互動。

舉例來說，您可以為運動應用程式設定健身摘要小工具，執行觸發 GET_EXERCISE_OBSERVATION BII 的使用者語音指令。當使用者透過「Ok Google，根據範例應用程式的數據，我這個禮拜跑了幾英里？」等要求時，Google 助理會主動顯示小工具。

有許多 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"。

• 設定 ImageView 元件的預設或預留位置圖片或圖示，例如 android:src="@drawable/my_widget_icon"。

如果沒有預設值，預覽畫面可能會顯示不正確或空白的值。這種做法的主要優點是，您可以提供本地化的預覽內容。

如需建立更複雜的預覽 (包含 ListView、GridView 或 StackView) 的建議方法，請參閱「建立包含動態項目的準確預覽」。

與可縮放小工具預覽的回溯相容性

如要讓 Android 11 (API 級別 30) 以下版本的小工具挑選器顯示小工具的預覽畫面，請指定 previewImage 屬性。

如果變更小工具的外觀，請更新預覽圖片。

新增小工具的說明

從 Android 12 開始，為小工具顯示的小工具挑選器提供說明。

使用 <appwidget-provider> 元素的 description 屬性提供小工具的說明：

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