本頁面由 Cloud Translation API 翻譯而成。

在小工具挑選器中新增生成的預覽畫面

產生的小工具預覽畫面可讓您建立動態的個人化小工具預覽畫面，準確反映小工具在使用者主畫面上的顯示方式。這些預覽畫面是透過推送 API 提供，也就是說，應用程式會在生命週期內的任何時間提供預覽畫面，不必接收來自小工具主機的明確要求。

如要提升應用程式的小工具選擇器體驗，請在 Android 15 以上版本裝置上提供產生的小工具預覽畫面，在 Android 12 至 Android 14 裝置上提供縮放的小工具預覽畫面 (方法是指定 previewLayout)，並在舊版裝置上提供 previewImage。

詳情請參閱 YouTube 上的「Enrich your app with live updates and widgets」。

設定應用程式，以便預覽生成的小工具

如要在搭載 Android 15 以上版本的裝置上顯示產生的動態小工具預覽畫面，請先在模組 build.gradle 檔案中將 compileSdk 值設為 35 以上，以便向小工具挑選器提供 RemoteViews。

應用程式隨後可以在 GlanceAppWidgetManager 或 AppWidgetManager 中使用 setWidgetPreview。為防止濫用行為並減輕系統健康問題，setWidgetPreview 是設有頻率限制的 API。預設上限為每小時約兩通電話。

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

如果是使用 Jetpack Glance 建立的小工具，請按照下列步驟操作：

覆寫 GlanceAppWidget.providePreview 函式，為預覽畫面提供可組合內容。如要在 provideGlance 中載入應用程式資料並傳遞至小工具的內容可組合函式，請確保預覽畫面顯示正確資料。與 provideGlance 不同，這是單一組合，不會重組或產生任何效果。
呼叫 GlanceAppWidgetManager.setWidgetPreviews 即可產生及發布預覽畫面。

系統不會提供預覽畫面，因此應用程式必須決定何時呼叫 setWidgetPreviews。更新策略取決於小工具的用途：

如果小工具含有靜態資訊或快速操作，請在首次啟動應用程式時設定預覽畫面。
應用程式有資料後，即可設定預覽畫面，例如使用者登入或完成初始設定後。
您可以設定定期工作，以所選頻率更新預覽畫面。

排解生成的預覽畫面問題

常見的問題是，產生預覽畫面後，相較於小工具的放置大小，預覽圖片可能會缺少圖片、圖示或其他可組合項。這個下拉式選單大小是由 targetCellWidth 和 targetCellHeight (如有指定) 定義，或是由應用程式小工具供應商資訊檔案中的 minWidth 和 minHeight 定義。

這是因為 Android 預設只會轉譯小工具最小尺寸可見的可組合函式。換句話說，Android 預設會將 previewSizeMode 設為 SizeMode.Single。系統會使用應用程式小工具供應器資訊 XML 中的 android:minHeight 和 android:minWidth，判斷要繪製哪些可組合函式。

如要修正這個問題，請在 GlanceAppWidget 中覆寫 previewSizeMode，並將其設為 SizeMode.Responsive，提供一組 DpSize 值。這會告知 Android 預覽畫面需要的所有版面配置大小，確保所有元素都能正確顯示。

針對特定板型規格進行最佳化。從最小值開始，根據小工具的中斷點提供 1 或 2 個大小。至少指定一張圖片，以確保回溯相容性。如要瞭解不同格線大小適用的最低 DP 值，請參閱小工具設計指南。

產生不含 Jetpack 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 屬性。

小工具預覽的回溯相容性

如要讓 Android 11 (API 級別 30) 以下版本的動態小工具選擇器顯示動態小工具的預覽畫面，或是做為產生的預覽畫面的備援，請指定 previewImage 屬性。

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

建立包含動態項目的準確預覽畫面

本節說明在具有集合檢視區塊的小工具 (即使用 ListView、GridView 或 StackView 的小工具) 的小工具預覽畫面中顯示多個項目的建議做法。這項功能不適用於系統產生的動態小工具預覽畫面。

如果小工具使用其中一個檢視區塊，直接提供實際小工具版面配置來建立可縮放的預覽畫面，會導致小工具預覽畫面未顯示任何項目時，使用者體驗不佳。這是因為集合檢視區塊資料是在執行階段動態設定，看起來與圖 1 所示的圖片類似。

如要讓小工具預覽畫面在小工具挑選器中正確顯示，建議您維護專為預覽畫面設計的獨立版面配置檔案。這個獨立版面配置檔案應包含下列項目：

實際的小工具版面配置。
含有虛擬項目的預留位置集合檢視區塊。舉例來說，您可以提供含有多個虛假清單項目的預留位置 LinearLayout，模擬 ListView。

如要說明 ListView 的範例，請先從個別版面配置檔案開始：

// res/layout/widget_preview.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:background="@drawable/widget_background"
   android:orientation="vertical">

    // Include the actual widget layout that contains ListView.
    <include
        layout="@layout/widget_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    // The number of fake items you include depends on the values you provide
    // for minHeight or targetCellHeight in the AppWidgetProviderInfo
    // definition.

    <TextView android:text="@string/fake_item1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

    <TextView android:text="@string/fake_item2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

</LinearLayout>

提供 AppWidgetProviderInfo 中繼資料的 previewLayout 屬性時，請指定預覽版面配置檔案。您仍須為 initialLayout 屬性指定實際的小工具版面配置，並在執行階段建構 RemoteViews 時使用實際的小工具版面配置。

<appwidget-provider
    previewLayout="@layout/widget_previe"
    initialLayout="@layout/widget_view" />

複雜的清單項目

上一節的範例提供的是虛擬清單項目，因為清單項目是 TextView 物件。如果項目是複雜的版面配置，提供虛假項目可能會更加複雜。

假設 widget_list_item.xml 中定義的清單項目包含兩個 TextView 物件：

<LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_title" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_content" />
</LinearLayout>

如要提供虛假的清單項目，您可以多次加入版面配置，但這樣會導致每個清單項目都相同。如要提供不重複的清單項目，請按照下列步驟操作：

為文字值建立一組屬性：

<resources>
    <attr name="widgetTitle" format="string" />
    <attr name="widgetContent" format="string" />
</resources>

使用下列屬性設定文字：

<LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="?widgetTitle" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="?widgetContent" />
</LinearLayout>

視需要建立多種樣式，以供預覽。重新定義每個樣式中的值：

<resources>

    <style name="Theme.Widget.ListItem">
        <item name="widgetTitle"></item>
        <item name="widgetContent"></item>
    </style>
    <style name="Theme.Widget.ListItem.Preview1">
        <item name="widgetTitle">Fake Title 1</item>
        <item name="widgetContent">Fake content 1</item>
    </style>
    <style name="Theme.Widget.ListItem.Preview2">
        <item name="widgetTitle">Fake title 2</item>
        <item name="widgetContent">Fake content 2</item>
    </style>

</resources>

在預覽版面配置中，對虛擬項目套用樣式：

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content" ...>

    <include layout="@layout/widget_view" ... />

    <include layout="@layout/widget_list_item"
        android:theme="@style/Theme.Widget.ListItem.Preview1" />

    <include layout="@layout/widget_list_item"
        android:theme="@style/Theme.Widget.ListItem.Preview2" />

</LinearLayout>

透過 Glance 建立應用程式小工具

使用 Glance 處理錯誤