Flexible Widget-Layouts bereitstellen

Auf dieser Seite werden Optimierungen für die Größe von Widgets und eine größere Flexibilität beschrieben, die in Android 12 (API-Level 31) eingeführt wurden. Außerdem erfahren Sie dort, wie Sie die Größe Ihres Widgets festlegen.

Verbesserte APIs für Widgetgrößen und ‑Layouts verwenden

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

1. Legen Sie zusätzliche Einschränkungen für die Größe von Widgets fest.

2. Responsive Layouts oder genaue Layouts bereitstellen

In früheren Android-Versionen können Sie die Größe eines Widgets mit den Extras OPTION_APPWIDGET_MIN_WIDTH, OPTION_APPWIDGET_MIN_HEIGHT, OPTION_APPWIDGET_MAX_WIDTH und OPTION_APPWIDGET_MAX_HEIGHT abrufen und dann die Größe des Widgets 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 genaue Layouts.

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

Android 12 bietet APIs, mit denen Sie die Größe Ihres Widgets auf verschiedenen Geräten mit unterschiedlichen Bildschirmgrößen zuverlässiger festlegen können.

Zusätzlich zu den vorhandenen Attributen minWidth, minHeight, minResizeWidth und minResizeHeight können Sie die folgenden neuen appwidget-provider-Attribute verwenden:

• targetCellWidth und targetCellHeight: Mit diesen Werten wird die Zielgröße des Widgets in Launcher-Rasterzellen definiert. Wenn diese Attribute definiert sind, werden sie anstelle von minWidth oder minHeight verwendet.

• maxResizeWidth und maxResizeHeight: Mit diesen Werten wird die maximale Größe festgelegt, auf die der Nutzer das Widget im Launcher ändern kann.

Im folgenden XML-Code wird gezeigt, 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, mehrere Layouts zu erstellen, die jeweils für eine Reihe von Größen gelten. 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 eine Liste von Layouts angegeben wird.

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

@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 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 160 × 200 dp bis 214 dp (nächster Grenzwert – 1) × 200 dp.

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

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.

Genaue Layouts angeben

Wenn nur wenige responsive Layouts möglich sind, können Sie stattdessen verschiedene Layouts bereitstellen, die auf die Größen zugeschnitten sind, in denen das Widget angezeigt wird. Das sind in der Regel zwei Größen für Smartphones (Hoch- und Querformat) und vier Größen für faltbare Geräte.

Um diese Lösung zu implementieren, muss Ihre App die folgenden Schritte ausführen:

1. „Überladen“ 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. Rufen Sie den Schlüssel AppWidgetManager.OPTION_APPWIDGET_SIZES über das Bundle auf.

Das folgende Codebeispiel zeigt, wie Sie genaue Layouts angeben.

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

@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 des Widgets festlegen

Für jedes Widget müssen targetCellWidth und targetCellHeight für Geräte mit Android 12 oder höher oder minWidth und minHeight für alle Android-Versionen definiert werden. Diese Werte geben an, wie viel Speicherplatz das Widget standardmäßig belegt. Wenn Nutzer jedoch ein Widget auf 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 die sie Widgets und Symbole einfügen können. Dieses Raster kann je nach Gerät variieren. Viele Smartphones bieten beispielsweise ein Raster von 5 × 4 und Tablets ein größeres Raster. Wenn das Widget hinzugefügt wird, wird es horizontal und vertikal so gedehnt, dass es die Mindestanzahl an Zellen einnimmt, die für die Einschränkungen für targetCellWidth und targetCellHeight auf Geräten mit Android 12 oder höher oder für die Einschränkungen für minWidth und minHeight auf Geräten mit Android 11 (API-Level 30) oder niedriger erforderlich sind.

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. Anhand der folgenden Tabelle können Sie die Mindestabmessungen Ihres Widgets auf einem typischen Smartphone mit 5 × 4 Rasterzellen grob abschätzen, je nach Anzahl der belegten Rasterzellen:

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 festzulegen.

Das liegt daran, dass die Zellenbreite im Hochformat in der Regel kleiner ist als im Querformat. Ebenso ist die Zellenhöhe im Querformat in der Regel kleiner als im Hochformat.

Wenn Sie beispielsweise möchten, dass die Breite des Widgets auf Google Pixel 4 auf eine Zelle verkleinert werden kann, müssen Sie minResizeWidth auf maximal 56 dp festlegen. Der Wert für das minResizeWidth-Attribut muss also kleiner als 57 dp sein, da eine Zelle im Hochformat mindestens 57 dp breit ist. Wenn Sie die Höhe des Widgets in einer Zelle auf demselben Gerät ändern möchten, müssen Sie minResizeHeight auf höchstens 50 dp festlegen, damit der Wert für das minResizeHeight-Attribut kleiner als 51 dp ist. Eine Zelle ist im Querformat mindestens 51 dp hoch.

Jedes Widget kann innerhalb der Größenbereiche zwischen den Attributen minResizeWidth/minResizeHeight und maxResizeWidth/maxResizeHeight geändert werden. Das bedeutet, dass es sich an alle Größenbereiche dazwischen anpassen muss.

Wenn Sie beispielsweise die Standardgröße des Widgets für die Platzierung festlegen möchten, können Sie 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 x 2 Zellen, wie in den Attributen targetCellWidth und targetCellHeight angegeben, oder 180 x 110 dp, wie in 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.

Mit den folgenden Attributen können Sie die unterstützten Größenbereiche Ihres Widgets festlegen:

<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 auf 530 dp und die Höhe von 110 dp auf 450 dp skaliert werden. Das Widget kann dann von 3 × 2 auf 5 × 2 Zellen vergrößert werden, sofern die folgenden Bedingungen erfüllt sind:

• Das Gerät hat das Raster 5 × 4.
• Die Zuordnung zwischen der Anzahl der Zellen und der verfügbaren Größe in Pixeln pro Zoll richtet sich nach der Tabelle mit der Schätzung der Mindestabmessungen auf dieser Seite.
• Das Widget passt sich diesem Größenbereich an.

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

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 Layout, das als R.layout.widget_weather_forecast_small angegeben ist, wird also von 180 × 110 dp (minResizeWidth × minResizeHeight) bis 269 × 279 dp (nächste Grenzwerte – 1) verwendet. 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, passt sich das Erscheinungsbild an die jeweilige Größe in den Zellen an, wie in den folgenden Beispielen zu sehen.