Auf dieser Seite werden Optimierungen der Widget-Größe und mehr Flexibilität beschrieben, die in Android 12 (API-Level 31) eingeführt wurden. Außerdem wird beschrieben, wie Sie eine Größe für das Widget bestimmen.
Verbesserte APIs für Widget-Größen und -Layouts verwenden
Ab Android 12 (API-Level 31) können Sie optimierte Größenattribute und flexible Layouts angeben. Gehen Sie dazu so vor, wie in den folgenden Abschnitten beschrieben:
Geben Sie zusätzliche Größenbeschränkungen für das Widget an.
Sie stellen responsive Layouts oder genaue Layouts bereit.
In früheren Android-Versionen ist es möglich, die Größenbereiche eines Widgets mit den Extras OPTION_APPWIDGET_MIN_WIDTH
, OPTION_APPWIDGET_MIN_HEIGHT
, OPTION_APPWIDGET_MAX_WIDTH
und OPTION_APPWIDGET_MAX_HEIGHT
abzurufen und dann die Größe des Widgets zu schätzen. Diese Logik funktioniert jedoch nicht in allen Situationen. Für Widgets, die auf Android 12 oder höher ausgerichtet sind, empfehlen wir das responsive Layout oder das genaue Layout.
Zusätzliche Größenbeschränkungen für Widgets angeben
In Android 12 werden APIs hinzugefügt, mit denen du dafür sorgen kannst, dass die Größe deines Widgets auf verschiedenen Geräten mit unterschiedlichen Bildschirmgrößen zuverlässiger ist.
Verwenden Sie zusätzlich zu den vorhandenen Attributen minWidth
, minHeight
, minResizeWidth
und minResizeHeight
die folgenden neuen appwidget-provider
-Attribute:
targetCellWidth
undtargetCellHeight
: Definieren Sie die Zielgröße des Widgets in Bezug auf die Zellen im Launcher-Raster. Wenn diese Attribute definiert sind, werden sie anstelle vonminWidth
oderminHeight
verwendet.maxResizeWidth
undmaxResizeHeight
: Definieren die maximale Größe, auf die der Launcher die Größe des Widgets anpassen kann.
Der folgende XML-Code zeigt, wie die Größenattribute verwendet werden.
<appwidget-provider
...
android:targetCellWidth="3"
android:targetCellHeight="2"
android:maxResizeWidth="250dp"
android:maxResizeHeight="110dp">
</appwidget-provider>
Responsive Layouts bereitstellen
Wenn sich das Layout je nach Größe des Widgets ändern muss, empfehlen wir, eine kleine Gruppe von Layouts zu erstellen, die jeweils für einen Bereich von Größen gültig sind. Sollte dies nicht möglich sein, haben Sie die Möglichkeit, Layouts basierend auf der exakten Widget-Größe zur Laufzeit bereitzustellen, wie auf dieser Seite beschrieben.
Diese Funktion ermöglicht eine reibungslosere Skalierung und insgesamt einen besseren Systemzustand, da das System die Anwendung nicht jedes Mal aktivieren muss, wenn das Widget in einer anderen Größe angezeigt wird.
Das folgende Codebeispiel zeigt, wie Sie eine Liste von Layouts bereitstellen.
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); }
Angenommen, das Widget hat die folgenden Attribute:
<appwidget-provider
android:minResizeWidth="160dp"
android:minResizeHeight="110dp"
android:maxResizeWidth="250dp"
android:maxResizeHeight="200dp">
</appwidget-provider>
Das obige Code-Snippet bedeutet Folgendes:
smallView
unterstützt 160 dp (minResizeWidth
) × 110 dp (minResizeHeight
) bis 160 dp × 199 dp (nächste Grenze – 1 dp).tallView
unterstützt 160 dp × 200 dp bis 214 dp (nächste Grenze: 1) × 200 dp.wideView
unterstützt 215 dp × 110 dp (minResizeHeight
) bis 250 dp (maxResizeWidth
) × 200 dp (maxResizeHeight
).
Das Widget muss einen Größenbereich von minResizeWidth
× minResizeHeight
bis maxResizeWidth
× maxResizeHeight
unterstützen. Innerhalb dieses Bereichs können Sie festlegen, wann das Layout gewechselt werden soll.
![Beispiel für ein responsives Layout](https://developer.android.com/static/images/appwidgets/size-range.gif?authuser=6&hl=de)
Genaue Layouts bereitstellen
Wenn eine kleine Anzahl responsiver Layouts nicht möglich ist, können Sie stattdessen verschiedene Layouts bereitstellen, die auf die Größen zugeschnitten sind, in denen das Widget angezeigt wird. Normalerweise sind das zwei Größen für Smartphones (Hoch- und Querformat) und vier Größen für faltbare Smartphones.
Zur Implementierung dieser Lösung muss Ihre Anwendung die folgenden Schritte ausführen:
Überlastung
AppWidgetProvider.onAppWidgetOptionsChanged()
, die aufgerufen wird, wenn sich der Satz von Größen ändert.Rufen Sie
AppWidgetManager.getAppWidgetOptions()
auf. Dadurch wird einBundle
-Objekt mit den Größen zurückgegeben.Greifen Sie über
Bundle
auf den SchlüsselAppWidgetManager.OPTION_APPWIDGET_SIZES
zu.
Das folgende Codebeispiel zeigt, wie exakte Layouts bereitgestellt werden.
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) { }
Größe für das Widget festlegen
Für jedes Widget müssen targetCellWidth
und targetCellHeight
für Geräte mit Android 12 oder höher bzw. minWidth
und minHeight
für alle Android-Versionen definiert werden, um anzugeben, wie viel Speicherplatz standardmäßig mindestens verbraucht. Wenn Nutzer jedoch ein Widget zu ihrem Startbildschirm hinzufügen, nimmt es in der Regel mehr als die von Ihnen angegebene Mindestbreite und -höhe ein.
Android-Startbildschirme bieten Nutzern ein Raster mit verfügbaren Bereichen, in denen sie Widgets und Symbole platzieren können. Dieses Raster kann je nach Gerät variieren. Viele Mobilgeräte haben beispielsweise ein 5 x 4-Raster und Tablets können ein größeres Raster bieten. Wenn das Widget hinzugefügt wird, wird es horizontal und vertikal so gestreckt, dass es die Mindestanzahl von Zellen einnimmt, die erforderlich sind, um die Einschränkungen für targetCellWidth
und targetCellHeight
auf Geräten mit Android 12 oder höher oder minWidth
und minHeight
auf Geräten mit Android 11 (API-Level 30) oder niedriger zu erfüllen.
Sowohl die Breite und Höhe einer Zelle als auch die Größe der automatischen Ränder, die auf Widgets angewendet werden, können je nach Gerät variieren. Verwenden Sie die folgende Tabelle, um die Mindestabmessungen Ihres Widgets in einem typischen 5x4-Raster-Handset grob anhand der gewünschten Anzahl der besetzten Rasterzellen zu schätzen:
Anzahl der Zellen (Breite x Höhe) | Verfügbare Größe im Hochformat (dp) | Verfügbare Größe im Querformat (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) |
Verwenden Sie die Zellengrößen im Hochformat, um die Werte festzulegen, die Sie für die Attribute minWidth
, minResizeWidth
und maxResizeWidth
angeben. In ähnlicher Weise können Sie die Zellengrößen im Querformat verwenden, um die Werte festzulegen, die Sie für die Attribute minHeight
, minResizeHeight
und maxResizeHeight
angeben.
Der Grund dafür ist, dass die Zellenbreite im Hochformat in der Regel kleiner als im Querformat ist und entsprechend kleiner im Querformat als im Hochformat ist.
Wenn du beispielsweise möchtest, dass die Breite des Widgets auf einem Google Pixel 4 bis zu einer Zelle verkleinert werden kann, musst du minResizeWidth
auf höchstens 56 dp festlegen. Dadurch wird sichergestellt, dass der Wert für das Attribut minResizeWidth
kleiner als 57 dp ist, da eine Zelle im Hochformat mindestens 57 dp breit ist.
Wenn Sie möchten, dass die Größe des Widgets in einer Zelle auf demselben Gerät geändert werden kann, müssen Sie minResizeHeight
auf höchstens 50 dp festlegen. Der Wert für das Attribut minResizeHeight
muss kleiner als 51 dp sein, da eine Zelle im Querformat mindestens 51 dp hoch ist.
Die Größe jedes Widgets kann innerhalb der Größenbereiche zwischen den Attributen minResizeWidth
/minResizeHeight
und maxResizeWidth
/maxResizeHeight
geändert werden, d. h., es muss an alle Größenbereiche zwischen ihnen angepasst werden.
Um die Standardgröße des Widgets bei der Platzierung festzulegen, können Sie beispielsweise die folgenden Attribute festlegen:
<appwidget-provider
android:targetCellWidth="3"
android:targetCellHeight="2"
android:minWidth="180dp"
android:minHeight="110dp">
</appwidget-provider>
Die Standardgröße des Widgets beträgt also 3 × 2 Zellen, wie durch die Attribute targetCellWidth
und targetCellHeight
angegeben, oder 180 × 110 dp, wie in minWidth
und minHeight
angegeben, wenn auf Geräten Android 11 oder niedriger ausgeführt wird. Im letzteren Fall kann die Größe der Zellen je nach Gerät variieren.
Außerdem kannst du die folgenden Attribute angeben, um die unterstützten Größenbereiche deines Widgets festzulegen:
<appwidget-provider
android:minResizeWidth="180dp"
android:minResizeHeight="110dp"
android:maxResizeWidth="530dp"
android:maxResizeHeight="450dp">
</appwidget-provider>
Wie durch die vorherigen Attribute angegeben, kann die Breite des Widgets von 180 dp bis 530 dp und die Höhe von 110 dp bis 450 dp geändert werden. Die Größe des Widgets kann dann von 3 x 2 in 5 x 2-Zellen geändert werden, sofern die folgenden Bedingungen erfüllt sind:
- Das Gerät hat das 5x4-Raster.
- Die Zuordnung zwischen der Anzahl der Zellen und der verfügbaren Größe in dps entspricht der Tabelle mit Schätzungen der Mindestabmessungen auf dieser Seite.
- Das Widget passt sich an diesen Größenbereich an.
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);
Angenommen, das Widget verwendet die responsiven Layouts, die in den vorherigen Code-Snippets definiert wurden. Das bedeutet, dass das als R.layout.widget_weather_forecast_small
angegebene Layout von 180 dp (minResizeWidth
) × 110 dp (minResizeHeight
) bis 269 × 279 dp (nächste Grenzpunkte – 1) verwendet wird. In ähnlicher Weise wird R.layout.widget_weather_forecast_medium
von 270 × 110 dp bis 270 × 279 dp und R.layout.widget_weather_forecast_large
von 270 × 280 dp bis 530 dp (maxResizeWidth
) × 450 dp (maxResizeHeight
) verwendet.
Wenn der Nutzer die Größe des Widgets ändert, ändert sich sein Erscheinungsbild, um sich an die jeweilige Zellengröße anzupassen, wie in den folgenden Beispielen gezeigt.
![Beispiel für ein Wetter-Widget in der kleinsten 3x2-Rastergröße Die Benutzeroberfläche zeigt den Standortnamen (Tokio), die Temperatur (14 °) und ein Symbol für teilweise bewölktes Wetter.](https://developer.android.com/static/images/appwidgets/weather-size-3x2.png?authuser=6&hl=de)
R.layout.widget_weather_forecast_small
.![Beispiel für ein Wetter-Widget im Format 4 x 2 „M“. Wenn Sie die Größe des Widgets auf diese Weise ändern, wird die gesamte UI der vorherigen Widget-Größe genutzt und das Label „Überwiegend bewölkt“ sowie eine Temperaturprognose von 16:00 bis 19:00 Uhr hinzugefügt.](https://developer.android.com/static/images/appwidgets/weather-size-4x2.png?authuser=6&hl=de)
R.layout.widget_weather_forecast_medium
.![Beispiel für ein Wetter-Widget in der Größe 5 x 2 „M“. Wenn Sie die Größe des Widgets auf diese Weise ändern, entspricht die Benutzeroberfläche der vorherigen Größe. Der einzige Unterschied ist, dass das Widget um eine Zellenlänge gestreckt wird, um mehr horizontalen Platz zu belegen.](https://developer.android.com/static/images/appwidgets/weather-size-5x2.png?authuser=6&hl=de)
R.layout.widget_weather_forecast_medium
.![Beispiel für ein Wetter-Widget im Format 5 x 3 „Large“ (L). Wenn Sie die Größe des Widgets auf diese Weise ändern, baut es auf der Benutzeroberfläche der vorherigen Widget-Größen auf und fügt im Widget eine Ansicht mit einer Wetterprognose für Dienstag und Mittwoch hinzu. Symbole, die sonniges oder regnerisches Wetter sowie hohe und niedrige Temperaturen für jeden Tag anzeigen.](https://developer.android.com/static/images/appwidgets/weather-size-5x3.png?authuser=6&hl=de)
R.layout.widget_weather_forecast_large
.![Beispiel für ein Wetter-Widget im Format 5 x 4 „Large“ (L). Wenn Sie die Größe des Widgets auf diese Weise ändern, wird auf der gesamten Benutzeroberfläche der vorherigen Widget-Größen gearbeitet. Dabei werden Donnerstag und Freitag (sowie die entsprechenden Symbole für die Wetterart sowie Höchst- und Tiefsttemperaturen für jeden Tag) hinzugefügt.](https://developer.android.com/static/images/appwidgets/weather-size-5x4.png?authuser=6&hl=de)
R.layout.widget_weather_forecast_large
.