提供彈性的小工具版面配置

本頁將說明 Android 12 (API 級別 31) 中推出的子結構大小精進功能，以及更彈性的設計。並詳細說明如何決定小工具的大小。

使用改善版 API 處理小工具大小和版面配置

從 Android 12 (API 級別 31) 開始，您可以透過下列操作提供更精細的大小屬性和彈性版面配置，如後續各節所述：

  1. 指定其他小工具大小限制。

  2. 提供回應式版面配置或確切版面配置。

在舊版 Android 中，您可以使用 OPTION_APPWIDGET_MIN_WIDTH、OPTION_APPWIDGET_MIN_HEIGHT、OPTION_APPWIDGET_MAX_WIDTH 和 OPTION_APPWIDGET_MAX_HEIGHT 額外項目，取得小工具的大小範圍，然後估算小工具的大小，但這項邏輯並非在所有情況下都適用。如果小工具指定 Android 12 以上版本，建議您提供回應式或確切版面配置。

指定其他小工具大小限制

Android 12 新增了 API，可讓您確保小工具在不同螢幕尺寸的裝置上，能更可靠地調整大小。

除了現有的 minWidth、minHeight、minResizeWidth 和 minResizeHeight 屬性外，請使用下列新的 appwidget-provider 屬性：

  • targetCellWidth 和 targetCellHeight：定義小工具的目標大小，以啟動器格狀檢視畫面的儲存格為單位。如果已定義，系統會使用這些屬性，而非 minWidth 或 minHeight。

  • maxResizeWidth 和 maxResizeHeight：定義啟動器允許使用者將小工具調整至的最大大小。

以下 XML 顯示如何使用大小屬性。

<appwidget-provider
  ...
  android:targetCellWidth="3"
  android:targetCellHeight="2"
  android:maxResizeWidth="250dp"
  android:maxResizeHeight="110dp">
</appwidget-provider>

提供回應式版面配置

如果版面配置需要根據小工具的大小而變更，建議您建立一小組版面配置，每個版面配置都適用於特定大小範圍。如果無法做到這一點，您可以選擇根據執行階段的確切小工具大小提供版面配置，如本頁所述。

這項功能可讓系統更順暢地縮放，整體系統健康狀況也因此獲得改善，因為系統不必每次顯示不同大小的小工具時，就喚醒應用程式。

以下程式碼範例說明如何提供版面配置清單。

Kotlin

override fun onUpdate(...) {
    val smallView = ...
    val tallView = ...
    val wideView = ...

    val viewMapping: Map<SizeF, RemoteViews> = mapOf(
            SizeF(150f, 100f) to smallView,
            SizeF(150f, 200f) to tallView,
            SizeF(215f, 100f) to wideView
    )
    val remoteViews = RemoteViews(viewMapping)

    appWidgetManager.updateAppWidget(id, remoteViews)
}

Java

@Override
public void onUpdate(...) {
    RemoteViews smallView = ...;
    RemoteViews tallView = ...;
    RemoteViews wideView = ...;

    Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
    viewMapping.put(new SizeF(150f, 100f), smallView);
    viewMapping.put(new SizeF(150f, 200f), tallView);
    viewMapping.put(new SizeF(215f, 100f), wideView);
    RemoteViews remoteViews = new RemoteViews(viewMapping);

    appWidgetManager.updateAppWidget(id, remoteViews);
}

假設小工具具有下列屬性：

<appwidget-provider
    android:minResizeWidth="160dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="200dp">
</appwidget-provider>

上述程式碼片段的意思如下：

  • smallView 支援 160dp (minResizeWidth) × 110dp (minResizeHeight) 到 160dp × 199dp (下一個截斷點 - 1dp)。
  • tallView 支援 160dp × 200dp 到 214dp (下一個截斷點 - 1) × 200dp。

  • wideView 支援 215dp × 110dp (minResizeHeight) 到 250dp (maxResizeWidth) × 200dp (maxResizeHeight)。

小工具必須支援 minResizeWidth × minResizeHeight 到 maxResizeWidth × maxResizeHeight 的大小範圍。在這個範圍內，您可以決定切換版面的截止點。

回應式版面配置範例
圖 1 回應式版面配置範例

提供確切的版面配置

如果無法使用一小組回應式版面配置，您可以提供不同版面配置，以配合小工具顯示的大小。這通常是兩種尺寸的手機 (直向和橫向模式)，以及四種尺寸的折疊式裝置。

如要實作此解決方案，應用程式需要執行下列步驟：

  1. 超載 AppWidgetProvider.onAppWidgetOptionsChanged()，當一組大小變更時會呼叫此函式。

  2. 呼叫 AppWidgetManager.getAppWidgetOptions()，該函式會傳回包含大小的 Bundle。

  3. 從 Bundle 存取 AppWidgetManager.OPTION_APPWIDGET_SIZES 鍵。

以下程式碼範例說明如何提供確切的版面配置。

Kotlin

override fun onAppWidgetOptionsChanged(
        context: Context,
        appWidgetManager: AppWidgetManager,
        id: Int,
        newOptions: Bundle?
) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, id, newOptions)
    // Get the new sizes.
    val sizes = newOptions?.getParcelableArrayList<SizeF>(
            AppWidgetManager.OPTION_APPWIDGET_SIZES
    )
    // Check that the list of sizes is provided by the launcher.
    if (sizes.isNullOrEmpty()) {
        return
    }
    // Map the sizes to the RemoteViews that you want.
    val remoteViews = RemoteViews(sizes.associateWith(::createRemoteViews))
    appWidgetManager.updateAppWidget(id, remoteViews)
}

// Create the RemoteViews for the given size.
private fun createRemoteViews(size: SizeF): RemoteViews { }

Java

@Override
public void onAppWidgetOptionsChanged(
    Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newOptions) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, appWidgetId, newOptions);
    // Get the new sizes.
    ArrayList<SizeF> sizes =
        newOptions.getParcelableArrayList(AppWidgetManager.OPTION_APPWIDGET_SIZES);
    // Check that the list of sizes is provided by the launcher.
    if (sizes == null || sizes.isEmpty()) {
      return;
    }
    // Map the sizes to the RemoteViews that you want.
    Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
    for (SizeF size : sizes) {
        viewMapping.put(size, createRemoteViews(size));
    }
    RemoteViews remoteViews = new RemoteViews(viewMapping);
    appWidgetManager.updateAppWidget(id, remoteViews);
}

// Create the RemoteViews for the given size.
private RemoteViews createRemoteViews(SizeF size) { }

決定小工具的大小

每個小工具都必須為搭載 Android 12 以上版本的裝置定義 targetCellWidth 和 targetCellHeight，或為所有 Android 版本定義 minWidth 和 minHeight，以指示預設會耗用的最小空間量。不過，當使用者將小工具新增到主畫面時，小工具通常會占用超過您指定的最小寬度和高度。

Android 主畫面會提供可用空間的格狀區域，讓使用者放置小工具和圖示。這個格線可能因裝置而異。舉例來說，許多手機提供 5x4 格線，而平板電腦則可能提供較大的格線。在新增小工具時，系統會將其橫向和縱向拉伸至所需的最低數量，以滿足搭載 Android 12 以上版本裝置的 targetCellWidth 和 targetCellHeight 限制條件，或是搭載 Android 11 (API 級別 30) 以下版本裝置的 minWidth 和 minHeight 限制條件。

資料列的寬度和高度，以及套用至小工具的自動邊界大小，都可能因裝置而異。請參考下表，根據所需佔用格狀單元的數量，粗略估算小工具在典型 5x4 格狀手機上的最小尺寸：

儲存格數量 (寬 x 高) 直向模式的可用大小 (dp) 橫向模式的可用大小 (dp)
1x1 57x102dp 127x51dp
2x1 130x102dp 269x51dp
3x1 203x102dp 412x51dp
4x1 276x102dp 554x51dp
5x1 349x102dp 697x51dp
5x2 349x220dp 697x117dp
5x3 349x337dp 697x184dp
5x4 349x455dp 697x250dp
... ... ...
n x m (73n - 16) x (118m - 16) (142n - 15) x (66m - 15)

請使用直向模式的儲存格大小，為 minWidth、minResizeWidth 和 maxResizeWidth 屬性提供值。同樣地，請使用橫向模式的儲存格大小，為 minHeight、minResizeHeight 和 maxResizeHeight 屬性提供值。

這是因為在直向模式下，儲存格寬度通常比橫向模式小，同樣地，儲存格高度在橫向模式下通常比在直向模式下小。

舉例來說，如果您希望在 Google Pixel 4 上將小工具的寬度縮減至一個單元格，就必須將 minResizeWidth 設為最多 56dp，確保 minResizeWidth 屬性的值小於 57dp，因為單元格在直向模式下的寬度至少為 57dp。同樣地，如果您希望小工具高度可在同一裝置的一個儲存格中調整大小，就必須將 minResizeHeight 設為最多 50dp，確保 minResizeHeight 屬性的值小於 51dp，因為在橫向模式下，一個儲存格的高度至少為 51dp。

每個小工具都可以在 minResizeWidth/minResizeHeight 和 maxResizeWidth/maxResizeHeight 屬性之間的大小範圍內調整大小，也就是說，它需要適應兩者之間的任何大小範圍。

舉例來說，如要設定放置位置的預設小工具大小，您可以設定下列屬性：

<appwidget-provider
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>

這表示小工具的預設大小為 3x2 個格，如 targetCellWidth 和 targetCellHeight 屬性所指定；如果是搭載 Android 11 以下版本的裝置，則大小為 180×110dp，如 minWidth 和 minHeight 所指定。在後一種情況下，單元格大小可能因裝置而異。

此外，如要設定小工具支援的大小範圍，您可以設定下列屬性：

<appwidget-provider
    android:minResizeWidth="180dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="530dp"
    android:maxResizeHeight="450dp">
</appwidget-provider>

如同上述屬性所指定，小工具的寬度可從 180dp 調整至 530dp，高度則可從 110dp 調整至 450dp。只要符合下列條件，小工具就能從 3x2 調整為 5x2 格：

  • 裝置有 5x4 格狀的螢幕。
  • 如要瞭解單元格數量與可用的 dp 大小之間的對應關係，請參閱本頁中的表格，其中顯示預估的最小尺寸。
  • 小工具會根據該尺寸範圍進行調整。

Kotlin

val smallView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_small)
val mediumView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_medium)
val largeView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_large)

val viewMapping: Map<SizeF, RemoteViews> = mapOf(
        SizeF(180f, 110f) to smallView,
        SizeF(270f, 110f) to mediumView,
        SizeF(270f, 280f) to largeView
)

appWidgetManager.updateAppWidget(appWidgetId, RemoteViews(viewMapping))

Java

RemoteViews smallView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_small);
RemoteViews mediumView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_medium);
RemoteViews largeView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_large);

Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
viewMapping.put(new SizeF(180f, 110f), smallView);
viewMapping.put(new SizeF(270f, 110f), mediumView);
viewMapping.put(new SizeF(270f, 280f), largeView);
RemoteViews remoteViews = new RemoteViews(viewMapping);

appWidgetManager.updateAppWidget(id, remoteViews);

假設小工具使用上述程式碼片段中定義的回應式版面配置。也就是說，從 180dp (minResizeWidth) x 110dp (minResizeHeight) 到 269x279dp (下一個截斷點 - 1)，會使用指定為 R.layout.widget_weather_forecast_small 的版面配置。同樣地，R.layout.widget_weather_forecast_medium 會用於 270x110dp 到 270x279dp，而 R.layout.widget_weather_forecast_large 會用於 270x280dp 到 530dp (maxResizeWidth) x 450dp (maxResizeHeight)。

當使用者調整小工具大小時，其外觀會根據單元格中的每個大小進行調整，如以下範例所示。

最小 3x2 格式大小的氣象小工具範例。使用者介面會顯示位置名稱 (東京)、溫度 (14°) 和表示局部多雲天氣的符號。
圖 2. 3x2 R.layout.widget_weather_forecast_small

4x2 的「中型」天氣小工具範例。以這種方式調整小工具大小時，系統會根據先前的小工具大小建立所有 UI，並新增「多雲」標籤，以及下午 4 點至 7 點的溫度預測資訊。
圖 3 4x2 R.layout.widget_weather_forecast_medium

5x2 的「中」大小天氣小工具範例。以這種方式調整小工具大小，會產生與先前大小相同的 UI，但會延伸一個格子的長度，以便佔用更多水平空間。
圖 4：5x2 R.layout.widget_weather_forecast_medium

5x3 的「大型」天氣小工具範例。以這種方式調整小工具大小時，系統會根據先前的小工具大小建立所有 UI，並在小工具中新增檢視畫面，其中包含星期二和星期三的天氣預報。符號表示晴天或雨天，以及每日高溫和低溫。
圖 5 5x3 R.layout.widget_weather_forecast_large

5x4 的「大型」天氣小工具範例。以這種方式調整小工具大小，可根據先前的小工具大小建立所有 UI，並新增星期四和星期五 (以及相應的符號，用於指出天氣類型以及每天的高溫和低溫)。
圖 6. 5x4 R.layout.widget_weather_forecast_large。