Flexible Widget-Layouts bereitstellen

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:

1. Geben Sie zusätzliche Größenbeschränkungen für das Widget an.

2. 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 und targetCellHeight: Definieren Sie die Zielgröße des Widgets in Bezug auf die Zellen im Launcher-Raster. Wenn diese Attribute definiert sind, werden sie anstelle von minWidth oder minHeight verwendet.

• maxResizeWidth und maxResizeHeight: 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.

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

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:

1. Überlastung AppWidgetProvider.onAppWidgetOptionsChanged(), die aufgerufen wird, wenn sich der Satz von Größen ändert.

2. Rufen Sie AppWidgetManager.getAppWidgetOptions() auf. Dadurch wird ein Bundle-Objekt 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 exakte Layouts bereitgestellt werden.

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

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.

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