本頁說明調整小工具大小和增加彈性的方式 Android 12 (API 級別 31) 中導入的功能。其中也詳細說明瞭 決定小工具的大小。
針對小工具大小和版面配置使用改良的 API
從 Android 12 (API 級別 31) 開始,您可以提供更多精細的大小 屬性和彈性版面配置, 以下部分:
在先前的 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
支援 160 dp (minResizeWidth
) × 110 dp (minResizeHeight
) 至 160dp × 199dp (下一個截止點 - 1dp)。tallView
支援 160 × 200 dp 到 214 dp (下一個截止點 - 1) × 200 dp。wideView
支援從 215 dp × 110 dp (minResizeHeight
) 到 250 dp (maxResizeWidth
) × 200 dp (maxResizeHeight
)。
小工具必須支援 minResizeWidth
× 以上的大小範圍
minResizeHeight
到 maxResizeWidth
× maxResizeHeight
。在該範圍內
您可以決定要切換版面配置的截止點。
![回應式版面配置範例](https://developer.android.com/static/images/appwidgets/size-range.gif?hl=zh-tw)
提供確切的版面配置
如果一部分的回應式版面配置無法使用,您可以改為提供 針對顯示小工具的大小,設計不同的版面配置。這是 手機通常有兩種尺寸 (直向和橫向模式) 和四種尺寸 折疊式裝置
如要實作這項解決方案,應用程式必須執行下列步驟:
超載
AppWidgetProvider.onAppWidgetOptionsChanged()
, 系統會在大小組合變更時呼叫此方法呼叫
AppWidgetManager.getAppWidgetOptions()
。 ,會傳回包含大小的Bundle
。從
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) { }
決定小工具的大小
每個小工具都必須為裝置定義 targetCellWidth
和 targetCellHeight
搭載 Android 12 以上版本 或 minWidth
和 minHeight
(適用於所有使用者)
指出應用程式會使用的最低空間量
根據預設。不過,當使用者將小工具新增到主畫面時
的事件播放次數超過您指定的最小寬度和高度。
Android 主畫面提供一個可用空間格狀,方便使用者瀏覽
放置小工具和圖示。這個網格會因裝置而異:例如
手機可提供 5x4 的格狀版面,而平板電腦則可呈現更大的格狀版面。使用小工具時
並延伸至佔用的儲存格數量下限。
以水平和垂直方向,滿足對
在執行中的裝置上,targetCellWidth
和targetCellHeight
Android 12 以上版本,或搭載 minWidth
和 minHeight
的限制
搭載 Android 11 (API 級別 30) 以下版本的裝置。
儲存格的寬度和高度,以及套用的自動邊界大小 提供的小工具會因裝置而異請使用下表粗略估算 一般 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 公尺 | (73n - 16) x (118 公尺 - 16) | (142n - 15) x (66 公尺 - 15) |
使用直向模式的儲存格大小,填入您提供的值。
minWidth
、minResizeWidth
和 maxResizeWidth
屬性。同樣地
以橫向模式儲存格大小
指出您提供的值
定義 minHeight
、minResizeHeight
和 maxResizeHeight
屬性。
這是因為在直向模式下,儲存格的寬度通常會比較小 與橫向模式相同 - 同樣地,儲存格高度通常 。
舉例來說,如果您希望將小工具寬度縮小成單一儲存格,
Google Pixel 4 必須將 minResizeWidth
的高度設定設為 56dp。
確保 minResizeWidth
屬性的值較小
,因為直向儲存格的寬度至少達到 57dp。
同樣地,如果您希望小工具高度可在
相同裝置,您需要將 minResizeHeight
設為最多 50dp
minResizeHeight
屬性的值小於
51 dp:因為在橫向模式中,一個儲存格的高度至少為 51dp。
您可以調整每個小工具的大小範圍
minResizeWidth
/minResizeHeight
和 maxResizeWidth
/maxResizeHeight
屬性,因此需要配合兩個屬性之間的任何大小範圍進行調整。
舉例來說,如要為刊登位置設定刊登位置的預設尺寸,您可以 設定下列屬性:
<appwidget-provider
android:targetCellWidth="3"
android:targetCellHeight="2"
android:minWidth="180dp"
android:minHeight="110dp">
</appwidget-provider>
這表示小工具的預設大小為 3x2 儲存格,如
targetCellWidth
和 targetCellHeight
屬性—或 180×110 dp,如
由 minWidth
和 minHeight
為執行中的裝置指定
Android 11 以下版本。如果是後者,儲存格中的大小
會因裝置而異。
此外,如要設定支援的小工具大小範圍,可以設定下列 屬性:
<appwidget-provider
android:minResizeWidth="180dp"
android:minResizeHeight="110dp"
android:maxResizeWidth="530dp"
android:maxResizeHeight="450dp">
</appwidget-provider>
如上述屬性所指定,小工具的寬度會 可調整大小的範圍為 180 dp 到 530 dp,高度可調整至 110 dp 到 450 dp。 接著,這個小工具可以從 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);
假設小工具採用上述定義的回應式版面配置
程式碼片段。也就是說,指定的
R.layout.widget_weather_forecast_small
使用範圍為 180 dp (minResizeWidth
) x
110 dp (minResizeHeight
) 到 269x279 dp (下一個截斷點 - 1)。同樣地
R.layout.widget_weather_forecast_medium
使用從 270x110 dp 到 270x279dp,
而 R.layout.widget_weather_forecast_large
則使用 270x280 dp
530 dp (maxResizeWidth
) x 450 dp (maxResizeHeight
)。
當使用者調整小工具大小時,圖示的外觀會隨之變更, 儲存格,如以下範例所示。
![最小 3x2 格狀空間的天氣小工具範例。UI 顯示
位置名稱 (東京)、溫度 (14°),以及表示位置的符號
天氣局部多雲。](https://developer.android.com/static/images/appwidgets/weather-size-3x2.png?hl=zh-tw)
R.layout.widget_weather_forecast_small
。![4x2「Medium」中的「天氣」小工具範例大小調整小工具大小
這樣就能以先前小工具大小的所有 UI 為基礎
並加上並提供
下午 4 點到晚上 7 點。](https://developer.android.com/static/images/appwidgets/weather-size-4x2.png?hl=zh-tw)
R.layout.widget_weather_forecast_medium
。![5x2「Medium」中的天氣小工具範例大小調整小工具大小
這種方式產生的 UI 會與先前的大小一致,但
拉長一個儲存格長度,以佔用更多水平空間。](https://developer.android.com/static/images/appwidgets/weather-size-5x2.png?hl=zh-tw)
R.layout.widget_weather_forecast_medium
。![5x3「大」中的天氣小工具範例大小調整小工具大小
這樣就能以先前小工具大小的所有 UI 為基礎
並在小工具內加入包含天氣預報資料的檢視畫面
每週二和週三表示晴天或雨天的符號
以及每天的高低溫](https://developer.android.com/static/images/appwidgets/weather-size-5x3.png?hl=zh-tw)
R.layout.widget_weather_forecast_large
。![5x4 大尺寸的天氣小工具範例大小調整小工具大小
這樣就能以先前小工具大小的所有 UI 為基礎
並加上週四和週五 (及其對應的符號)
指出天氣類型,以及高低溫
每日費用)。](https://developer.android.com/static/images/appwidgets/weather-size-5x4.png?hl=zh-tw)
R.layout.widget_weather_forecast_large
。