強化小工具

本頁面提供自 Android 12 (API 級別 31) 起提供的選用小工具強化功能詳細資料。這些功能屬於選用功能，但實作方式簡單，而且可改善使用者的小工具體驗。

使用動態色彩

從 Android 12 開始，小工具可使用裝置主題顏色做為按鈕、背景和其他元件的顏色。這麼做可在不同小工具之間提供更流暢的轉場效果和一致性。

動態色彩有兩種設定方式：

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

• 使用 Android 適用的 Material 元件程式庫中的 Material 3 主題 (Theme.Material3.DynamicColors.DayNight)，該主題自 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. 淺色主題的小工具。

圖 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 和 Android Auto 等 Google 助理介面上顯示小工具。使用者可以選擇將 Google 助理顯示的小工具釘選到啟動器，鼓勵他們日後與應用程式互動。

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

有數十個 BII 涵蓋多個類別的使用者互動，幾乎所有 Android 應用程式都能透過這些 BII 強化其語音小工具。如要開始使用，請參閱「整合應用程式動作與 Android 小工具」。

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

在 Android 12 中，您可以新增經過調整的小工具預覽畫面和小工具說明。您可以使用產生的預覽畫面，改善應用程式的小工具挑選器體驗。

為改善應用程式的小工具挑選器體驗，請在 Android 15 以上版本的裝置上提供產生的「小工具」預覽畫面，在 Android 12 至 Android 14 裝置上提供經過縮放的「小工具」預覽畫面 (請指定 previewLayout)，並在較舊版本上提供 previewImage。

將產生的預覽畫面新增至小工具挑選器

應用程式必須在模組 build.gradle 檔案中將 compileSdk 值設為 35 以上，才能在 Android 15 以上版本裝置上，將 RemoteViews 提供給小工具挑選器。這表示應用程式可以更新挑選器中的內容，以更貼近使用者所見。

應用程式可以使用 AppWidgetManager、setWidgetPreview 和 getWidgetPreview 方法，更新小工具的外觀，以便顯示最新的個人化資訊。

使用 Jetpack Glance 產生更新的預覽畫面

Glance.compose 會執行一個組合，因此可組合函式的內容不會使用暫停函式、流程或類似的非同步呼叫。請改用常數資料。

以下範例使用 Jetpack Glance 產生更新後的預覽畫面。compileSdk 建構設定必須為 35 以上，setWidgetPreview 才能在這個程式碼片段中顯示為方法。

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)
AppWidgetSnippets.kt

不使用 Jetpack Glance 產生更新的預覽畫面

您可以不使用 Glance 就使用 RemoteViews。以下範例會載入 XML 小工具版面配置資源，並將其設為預覽畫面。如要讓 setWidgetPreview 在程式碼片段中顯示為方法，必須將 compileSdk 建構設定設為 35 以上。

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

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

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

圖 3. 小工具預覽畫面預設會顯示在 3x3 區域，但由於 XML 版面配置，因此可以放入 3x1 區域。

如要顯示準確的預覽畫面，您可以直接完成下列步驟，為實際的小工具版面配置提供預設值：

• 為 TextView 元素設定 android:text="@string/my_widget_item_fake_1"。

  注意： 使用 tools 標記設定的值 (例如 tools:text="@string/my_wdiget_item_fake_1") 不會顯示在預覽畫面中。

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

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

如要進一步瞭解包含 ListView、GridView 或 StackView 的複雜預覽畫面建議做法，請參閱「建立包含動態項目的精確預覽畫面」一文。

回溯相容性與可調整大小的小工具預覽畫面

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

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

為小工具新增名稱

小工具在小工具挑選器中顯示時，名稱不得重複。

小工具名稱會從 AndroidManifest.xml 檔案中小工具 receiver 元素的 label 屬性載入。

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

新增小工具的說明

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

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

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