Flexible Widget-Layouts bereitstellen

Compose ausprobieren
Jetpack Compose ist das empfohlene UI-Toolkit für Android. Hier erfährst du, wie du Widgets mit Compose-ähnlichen APIs erstellst.
Jetpack Glance →

Auf dieser Seite werden die in Android 12 (API-Level 31) eingeführten Verbesserungen bei der Widget-Größe und die größere Flexibilität beschrieben. Außerdem wird beschrieben, wie Sie die Größe Ihres Widgets bestimmen.

Verbesserte APIs für Widget-Größen und -Layouts verwenden

Ab Android 12 (API-Level 31) können Sie genauere Größenattribute und flexible Layouts bereitstellen. Gehen Sie dazu wie in den folgenden Abschnitten beschrieben vor:

  1. Zusätzliche Einschränkungen für die Widget-Größe angeben

  2. Bereitstellung von responsiven Layouts oder exakten Layouts.

In früheren Android-Versionen war es möglich, die Größenbereiche eines Widgets mithilfe der 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, responsive oder exakte Layouts bereitzustellen.

Zusätzliche Einschränkungen für die Widget-Größe angeben

In Android 12 wurden APIs hinzugefügt, mit denen Sie dafür sorgen können, dass Ihr Widget auf verschiedenen Geräten mit unterschiedlichen Bildschirmgrößen zuverlässiger skaliert wird.

Verwenden Sie zusätzlich zu den vorhandenen Attributen minWidth, minHeight, minResizeWidth und minResizeHeight die folgenden neuen appwidget-provider-Attribute:

  • targetCellWidth und targetCellHeight: Definieren die Zielgröße des Widgets in Bezug auf die Rasterzellen des Launchers. Wenn diese Attribute definiert sind, werden sie anstelle von minWidth oder minHeight verwendet.

  • maxResizeWidth und maxResizeHeight: Definieren die maximale Größe, auf die der Nutzer die Größe des Widgets im Launcher ändern kann.

Im folgenden XML-Beispiel wird gezeigt, wie die Größenattribute verwendet werden.

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
  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 Anzahl von Layouts zu erstellen, die jeweils für einen bestimmten Größenbereich gültig sind. Wenn das nicht möglich ist, können Sie auch Layouts basierend auf der genauen Widget-Größe zur Laufzeit bereitstellen, wie auf dieser Seite beschrieben.

Diese Funktion ermöglicht eine reibungslosere Skalierung und eine insgesamt bessere Systemleistung, da das System die App nicht jedes Mal aktivieren muss, wenn das Widget in einer anderen Größe angezeigt wird.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine Liste von Layouts bereitstellen.

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

    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)
}

Angenommen, das Widget hat die folgenden Attribute:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="160dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="200dp">
</appwidget-provider>

Das vorherige Code-Snippet bedeutet Folgendes:

  • smallView unterstützt von 160 dp (minResizeWidth) × 110 dp (minResizeHeight) bis 160 dp × 199 dp (nächster Grenzwert – 1 dp).
  • tallView unterstützt von 160 dp × 200 dp bis 214 dp (nächster Grenzwert – 1) × 200 dp.

  • wideView unterstützt von 215 dp × 110 dp (minResizeHeight) bis 250 dp (maxResizeWidth) × 200 dp (maxResizeHeight).

Ihr Widget muss den Größenbereich von minResizeWidth × minResizeHeight bis maxResizeWidth × maxResizeHeight unterstützen. Innerhalb dieses Bereichs können Sie den Grenzwert für den Layoutwechsel festlegen.

Beispiel für ein responsives Layout
Abbildung 1. Beispiel für ein responsives Layout

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. In der Regel sind das zwei Größen für Smartphones (Hoch- und Querformat) und vier Größen für faltbare Geräte.

Zur Implementierung dieser Lösung müssen in Ihrer App die folgenden Schritte ausgeführt werden:

  1. Überladen Sie AppWidgetProvider.onAppWidgetOptionsChanged(), das aufgerufen wird, wenn sich die Größen ändern.

  2. Rufen Sie AppWidgetManager.getAppWidgetOptions() auf. Dadurch wird ein Bundle mit den Größen zurückgegeben.

  3. Greifen Sie über Bundle auf den Schlüssel AppWidgetManager.OPTION_APPWIDGET_SIZES zu.

Das folgende Codebeispiel zeigt, wie Sie genaue Layouts bereitstellen.

override fun onAppWidgetOptionsChanged(
    context: Context,
    appWidgetManager: AppWidgetManager,
    id: Int,
    newOptions: Bundle?
) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, id, newOptions)
    // Get the new sizes.
    val sizes = newOptions?.let {
        BundleCompat.getParcelableArrayList(
            it,
            AppWidgetManager.OPTION_APPWIDGET_SIZES,
            SizeF::class.java
        )
    }
    // 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 {
}

Größe für das Widget festlegen

Für jedes Widget muss ein targetCellWidth und ein targetCellHeight für Geräte mit Android 12 oder höher oder ein minWidth und ein minHeight für alle Android-Versionen definiert werden, um den standardmäßig belegten Mindestspeicherplatz anzugeben. Wenn Nutzer jedoch ein Widget zu ihrem Startbildschirm hinzufügen, belegt es in der Regel mehr als die von Ihnen angegebene Mindestbreite und -höhe.

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 Smartphones bieten beispielsweise ein 5×4-Raster, während Tablets ein größeres Raster haben können. Wenn das Widget hinzugefügt wird, wird es so gestreckt, dass es die Mindestanzahl von Zellen horizontal und vertikal belegt, die erforderlich sind, um die Einschränkungen für targetCellWidth und targetCellHeight auf Geräten mit Android 12 oder höher oder die Einschränkungen für minWidth und minHeight auf Geräten mit Android 11 (API-Level 30) oder niedriger zu erfüllen.

Zellenabmessungen und automatische Ränder variieren je nach Gerät. Anhand der folgenden Tabelle kannst du die Mindestabmessungen deines Widgets auf einem typischen Smartphone mit einem 5x4-Raster schätzen, wenn du die gewünschte Anzahl belegter Rasterzellen angibst:

Anzahl der Zellen (Breite × Höhe) Verfügbare Größe im Porträtmodus (dp) Verfügbare Größe im Querformat (dp)
1x1 57 x 102 dp 127 × 51 dp
2x1 130 × 102 dp 269 x 51 dp
3x1 203 x 102 dp 412 × 51 dp
4x1 276 × 102 dp 554 × 51 dp
5x1 349 × 102 dp 697 × 51 dp
5x2 349 × 220 dp 697 × 117 dp
5x3 349 × 337 dp 697 × 184 dp
5 x 4 349 × 455 dp 697 × 250 dp
… … …
n x m (73n - 16) x (118m - 16) (142n - 15) x (66m - 15)

Verwenden Sie die Zellengrößen im Porträtmodus, um die Werte für die Attribute minWidth, minResizeWidth und maxResizeWidth anzugeben. Verwenden Sie die Zellengrößen im Querformat, um die Werte für die Attribute minHeight, minResizeHeight und maxResizeHeight anzugeben.

Das liegt daran, dass die Zellenbreite im Hochformat normalerweise kleiner ist als im Querformat. Entsprechend ist die Zellenhöhe im Querformat normalerweise kleiner als im Hochformat.

Wenn Sie beispielsweise möchten, dass die Breite Ihres Widgets auf einem Google Pixel 4 auf eine Zelle verkleinert werden kann, müssen Sie minResizeWidth auf maximal 56 dp festlegen, damit der Wert für das Attribut minResizeWidth kleiner als 57 dp ist, da eine Zelle im Hochformat mindestens 57 dp breit ist. Wenn die Höhe des Widgets in einer Zelle auf demselben Gerät anpassbar sein soll, müssen Sie minResizeHeight auf höchstens 50 dp festlegen, damit der Wert für das Attribut minResizeHeight kleiner als 51 dp ist, 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 angepasst werden. Das bedeutet, dass es sich an alle Größenbereiche dazwischen anpassen muss.

Wenn Sie beispielsweise die Standardgröße des Widgets bei der Platzierung festlegen möchten, können Sie die folgenden Attribute festlegen:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>

Das bedeutet, dass die Standardgröße des Widgets 3 × 2 Zellen beträgt, wie durch die Attribute targetCellWidth und targetCellHeight angegeben, oder 180 × 110 dp, wie durch minWidth und minHeight für Geräte mit Android 11 oder niedriger angegeben. Im letzteren Fall kann die Größe in Zellen je nach Gerät variieren.

Außerdem kannst du die folgenden Attribute festlegen, um die unterstützten Größenbereiche deines Widgets festzulegen:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="180dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="530dp"
    android:maxResizeHeight="450dp">
</appwidget-provider>

Wie in den vorherigen Attributen angegeben, kann die Breite des Widgets von 180 dp bis 530 dp und die Höhe von 110 dp bis 450 dp angepasst werden. Die Größe des Widgets kann dann von 3 × 2 auf 5 × 2 Zellen geändert werden, sofern die folgenden Bedingungen erfüllt sind:

  • Das Gerät hat ein 5×4-Raster.
  • Die Zuordnung zwischen der Anzahl der Zellen und der verfügbaren Größe in dps folgt der Tabelle mit der Schätzung der Mindestabmessungen auf dieser Seite.
  • Das Widget wird an diesen Größenbereich angepasst.

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

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) x 110 dp (minResizeHeight) bis 269 x 279 dp (nächste Grenzwerte – 1) verwendet wird. Ebenso 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, wird die Darstellung an die jeweilige Größe in Zellen angepasst, wie in den folgenden Beispielen gezeigt.

Beispiel für ein Wetter-Widget in der kleinsten Größe (3 × 2-Raster) Auf der Benutzeroberfläche werden der Name des Standorts (Tokio), die Temperatur (14 °C) und ein Symbol für teilweise bewölktes Wetter angezeigt.
Abbildung 2. 3 × 2 R.layout.widget_weather_forecast_small.

Beispiel für ein Wetter-Widget in der Größe 4 × 2 (mittelgroß) Wenn Sie die Größe des Widgets auf diese Weise anpassen, wird die gesamte Benutzeroberfläche der vorherigen Widget-Größe übernommen und das Label „Überwiegend bewölkt“ sowie eine Vorhersage der Temperaturen von 16:00 bis 19:00 Uhr hinzugefügt.
Abbildung 3. 4 × 2 R.layout.widget_weather_forecast_medium.

Beispiel für ein Wetter-Widget in der mittleren Größe 5 × 2 Wenn Sie die Größe des Widgets auf diese Weise ändern, wird dieselbe Benutzeroberfläche wie bei der vorherigen Größe angezeigt, nur dass sie um eine Zellenlänge gestreckt wird, um mehr horizontalen Platz einzunehmen.
Abbildung 4. 5 × 2 R.layout.widget_weather_forecast_medium.

Beispiel für ein Wetter-Widget in der Größe 5 × 3 (groß). Wenn Sie die Größe des Widgets auf diese Weise anpassen, werden alle UI-Elemente der vorherigen Widget-Größen übernommen und eine Ansicht im Widget hinzugefügt, die eine Wettervorhersage für Dienstag und Mittwoch enthält. Symbole für sonniges oder regnerisches Wetter sowie die Höchst- und Tiefsttemperaturen für jeden Tag.
Abbildung 5. 5 × 3 R.layout.widget_weather_forecast_large.

Beispiel für ein Wetter-Widget in der Größe 5 × 4 (groß) Wenn Sie die Größe des Widgets auf diese Weise ändern, werden alle UI-Elemente der vorherigen Widget-Größen übernommen und Donnerstag und Freitag (und die entsprechenden Symbole für die Wetterart sowie die Höchst- und Tiefsttemperatur für jeden Tag) hinzugefügt.
Abbildung 6. 5 x 4 R.layout.widget_weather_forecast_large.