強化小工具

本頁詳細說明可用的小工具強化功能 從 Android 12 (API 級別 31) 開始。這些功能為選用功能 提供簡便的使用體驗以及小工具使用體驗。

使用動態色彩

從 Android 12 開始，小工具可以使用裝置主題顏色 適用於按鈕、背景及其他元件如此一來 提高不同小工具之間的轉換和一致性

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

• 使用系統的預設主題 (@android:style/Theme.DeviceDefault.DayNight)。

• 請使用Theme.Material3.DynamicColors.DayNight Material Design 元件 Android 程式庫，從 Android Material 元件 1.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.淺色主題的小工具。

，瞭解如何調查及移除這項存取權。

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

注意： 請參閱「樣式和主題」一文 關於如何處理不同樣式、顏色、屬性和主題的深入指南。

啟用語音支援功能

讓 Google 助理支援應用程式動作 顯示小工具以回應相關使用者語音指令。透過設定 回應內建意圖 (BII) 的小工具， 應用程式可以主動在 Android 和 iOS 等 Google 助理介面顯示小工具 Android Auto使用者可以選擇固定 Google 助理顯示的小工具 啟動器，提高日後的互動性。

例如，您可以為運動應用程式設定運動摘要小工具 執行觸發 GET_EXERCISE_OBSERVATION敬上 BII。使用者觸發此 BII 時，Google 助理會主動顯示小工具 提出要求，例如：「Ok Google，我這週跑了幾英里？」 範例應用程式？」

有數十種 BII 涵蓋多種使用者互動方式， 幾乎所有 Android 應用程式都能強化語音小工具。首先 請參閱「整合應用程式動作與 Android 小工具」。

改善應用程式的小工具挑選器體驗

Android 12 可改善以下項目的小工具挑選器體驗： 來加入動態小工具預覽和小工具說明。

在小工具挑選器中新增可調整的小工具預覽畫面

自 Android 12 起，小工具預覽畫面會顯示在 小工具挑選器是可擴充的您要提供小工具的 XML 版面配置，並將其設為 預設大小先前，小工具預覽為靜態可繪製資源 某些情況導致預覽畫面無法正確反映小工具在 系統會將他們新增到主畫面。

如要實作可擴充的小工具預覽，請使用 previewLayout敬上 的 appwidget-provider 元素屬性，改為提供 XML 版面配置：

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

建議您使用與實際小工具相同的版面配置，並使用實際預設值 或測試值大多數應用程式都使用相同的 previewLayout 和 initialLayout。適用對象 瞭解如何建立準確的預覽版面配置，詳情請參閱下文的下一節 頁面。

建議您同時指定 previewLayout 和 previewImage 屬性 ，這樣一來，如果使用者的裝置，您的應用程式就能改回使用 previewImage 不支援 previewLayout，previewLayout 屬性的優先順序 超過 previewImage 屬性

建立精確預覽的建議做法

如要實作可擴充的小工具預覽，請使用 previewLayout 屬性的 提供 XML 版面配置的 appwidget-provider 元素：

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

圖 3.這是預設小工具預覽畫面 會顯示在 3x3 區域中，但因為採用 XML 版面配置，所以能容納 3x1 區域。

直接提供實際顯示的小工具，就能顯示精確的預覽畫面 完成下列步驟，以使用預設值：

• 正在為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，請參閱「建立包含動態效果的準確預覽」 項目。

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

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

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

新增小工具的說明

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

圖 4. 小工具挑選器顯示小工具範例 及其說明

使用description <appwidget-provider> 元素：

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

注意： 簡明扼要。沒有字元限制 說明的可用空間可能因裝置而異。

您可以使用 descriptionRes敬上 屬性，但小工具會忽略該屬性 。

啟用更流暢的轉場效果

從 Android 12 開始，啟動器可讓轉場效果更加順暢 當使用者透過小工具啟動應用程式時。

如要啟用這項經過改善的轉場效果，請使用 @android:id/background 或 android.R.id.background 用來識別背景元素：

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

警告： 請避免使用廣播訊息 彈跳床。 從 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);