Flexible Widget-Layouts bereitstellen

Auf dieser Seite werden Optimierungen der Widget-Größe und größere Flexibilität beschrieben. in Android 12 (API-Level 31) eingeführt. 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-Level 31) können Sie detailliertere Größenangaben machen Attribute und flexible Layouts. Gehen Sie dazu wie in den folgenden Abschnitten:

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 Größenbeschränkungen für Widgets angeben

Unter Android 12 werden APIs hinzugefügt, mit denen du prüfen kannst, ob dein Widget zuverlässiger auf verschiedenen Geräten mit unterschiedlichen Bildschirmgrößen.

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

• targetCellWidth und targetCellHeight: Definieren Sie die Zielgröße des Widgets in Bezug auf Zellen im Launcher-Raster. Wenn definiert sind, werden diese Attribute 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.

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, mehrere Layouts zu erstellen, die jeweils für eine Reihe von Größen gelten. Wenn dieses nicht möglich ist, besteht eine andere Möglichkeit darin, Layouts basierend auf dem genauen Widget zur Laufzeit, wie auf dieser Seite beschrieben.

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

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 dp × 110 dp (minResizeHeight) bis 250 dp (maxResizeWidth) × 200dp (maxResizeHeight).

Dein Widget muss folgende Größen unterstützen: minResizeWidth × minResizeHeight bis maxResizeWidth × maxResizeHeight. Innerhalb dieses Bereichs können Sie festlegen, wann das Layout gewechselt werden soll.

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.

Zur Implementierung dieser Lösung muss Ihre Anwendung die folgenden Schritte ausführen:

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

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 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 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 zu ihrem Startbildschirm hinzufügen, die angegebene Mindestbreite und -höhe überschreitet.

Android-Startbildschirme bieten Nutzenden ein Raster mit verfügbaren Bereichen, auf denen sie Widgets und Symbole zu platzieren. Dieses Raster kann je nach Gerät variieren. zum Beispiel viele Mobiltelefone haben ein 5x4-Raster und Tablets können ein größeres Raster bieten. Wenn das Widget wird er so gestreckt, dass er die Mindestanzahl von Zellen belegt, horizontal und vertikal angeordnet sein, um die Einschränkungen targetCellWidth und targetCellHeight auf aktiven Geräten Android 12 oder höher oder Einschränkungen für minWidth und minHeight bei Geräte mit Android 11 (API-Level 30) oder niedriger

Sowohl die Breite und Höhe einer Zelle als auch die Größe der automatisch angewendeten Ränder kann je nach Gerät variieren. Verwenden Sie die folgende Tabelle für eine grobe Schätzung. eines typischen 5x4-Raster-Handsets unter Berücksichtigung der Anzahl der gewünschten belegten Rasterzellen:

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

Der Grund dafür ist, dass die Zellenbreite im Hochformat in der Regel kleiner ist. als im Querformat. Die Zellenhöhe ist typischerweise im Querformat 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 möchten, dass die Größe des Widgets in einer Zelle im Gerät verwendet haben, müssen Sie minResizeHeight auf höchstens 50 dp einstellen, der Wert für das Attribut minResizeHeight ist kleiner als 51 dp, da eine Zelle im Querformat mindestens 51 dp hoch ist.

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

Um beispielsweise die Standardgröße des Widgets für die Platzierung festzulegen, können Sie Legen Sie die folgenden Attribute fest:

<appwidget-provider
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>

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

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 5x4-Raster.
• Zuordnung zwischen der Anzahl der Zellen und der verfügbaren Größe in dps entspricht der Tabelle mit der Schätzung des Minimums 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 Layout, das als R.layout.widget_weather_forecast_small angegeben ist, wird also von 180 dp (minResizeWidth) × 110 dp (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.