Flexible Widget-Layouts bereitstellen

Jetpack Compose verwenden
Jetpack Compose ist das empfohlene UI-Toolkit für Android. Hier erfahren Sie, wie Sie Widgets mit Compose-APIs erstellen.
Jetpack Glance →

Auf dieser Seite werden die Verbesserungen für die Widget-Größenanpassung und die größere Flexibilität beschrieben, die in Android 12 (API-Level 31) eingeführt wurden. Außerdem wird erläutert, wie Sie eine Größe für Ihr Widget festlegen .

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 angeben. Gehen Sie dazu so vor, wie in den folgenden Abschnitten beschrieben:

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

  2. Responsive Layouts oder genaue Layouts bereitstellen.

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

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

In Android 12 wurden APIs hinzugefügt, mit denen Sie sicherstellen können, dass die Größe Ihres Widgets auf verschiedenen Geräten mit unterschiedlichen Bildschirmgrößen zuverlässiger angepasst wird.

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 Launcher-Rasterzellen. Wenn diese Attribute definiert sind, werden sie anstelle von minWidth oder minHeight verwendet.

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

Im folgenden XML 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, 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.

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 vorherige Code-Snippet bedeutet Folgendes:

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

  • wideView unterstützt Größen 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 Wechsel des Layouts 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.

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

  1. AppWidgetProvider.onAppWidgetOptionsChanged() überladen. Diese Methode wird aufgerufen, wenn sich die Anzahl der Größen ändert.

  2. AppWidgetManager.getAppWidgetOptions() aufrufen. Diese Methode gibt ein Bundle mit den Größen zurück.

  3. Auf den AppWidgetManager.OPTION_APPWIDGET_SIZES Schlüssel aus dem Bundle zugreifen.

Im folgenden Codebeispiel wird gezeigt, wie Sie genaue Layouts bereitstellen.

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 Ihr Widget festlegen

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

Auf Android-Startbildschirmen wird Nutzern ein Raster mit verfügbaren Bereichen angezeigt, 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 und Tablets können ein größeres Raster haben. Wenn Ihr Widget hinzugefügt wird, wird es so angepasst, 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.

Sowohl die Breite als auch die Höhe einer Zelle und die Größe der automatischen Ränder, die auf Widgets angewendet werden, können je nach Gerät variieren. In der folgenden Tabelle können Sie die Mindestabmessungen Ihres Widgets auf einem typischen Smartphone mit 5 × 4-Raster ungefähr schätzen, je nachdem, wie viele Rasterzellen es belegen soll:

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

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

Der Grund dafür ist, dass die Zellbreite im Hochformat in der Regel kleiner ist als im Querformat. Entsprechend ist die Zellenhöhe im Querformat in der Regel kleiner als im Hochformat.

Wenn Sie beispielsweise möchten, dass die Breite Ihres Widgets auf einem Google Pixel 4 auf eine Zelle reduziert werden kann, müssen Sie minResizeWidth auf maximal 56 dp festlegen, damit der Wert für das Attribut minResizeWidth kleiner als 57 dp ist. Eine Zelle ist im Hochformat mindestens 57 dp breit. Wenn Sie entsprechend möchten, dass die Höhe Ihres Widgets auf demselben Gerät auf eine Zelle reduziert werden kann, müssen Sie minResizeHeight auf maximal 50 dp festlegen, damit der Wert für das Attribut minResizeHeight kleiner als 51 dp ist. Eine Zelle ist im Querformat mindestens 51 dp hoch.

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 zwischen diesen Attributen 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
    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. Für Geräte mit Android 11 oder niedriger ist die Standardgröße 180 × 110 dp, wie durch minWidth und minHeight angegeben. Im letzteren Fall kann die Größe in Zellen je nach Gerät variieren.

Außerdem können Sie die unterstützten Größenbereiche Ihres Widgets mit den folgenden Attributen 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 angepasst werden. Die Größe des Widgets kann dann von 3 × 2 auf 5 × 2 Zellen angepasst 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 dp entspricht der Tabelle mit der Schätzung der Mindest abmessungen 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 für Größen von 180 dp (minResizeWidth) × 110 dp (minResizeHeight) bis 269 × 279 dp (nächste Grenzwerte – 1) verwendet wird. Entsprechend wird R.layout.widget_weather_forecast_medium für Größen von 270 × 110 dp bis 270 × 279 dp und R.layout.widget_weather_forecast_large für Größen von 270 × 280 dp bis 530 dp (maxResizeWidth) × 450 dp (maxResizeHeight) verwendet.

Wenn der Nutzer die Größe des Widgets ändert, ändert sich auch sein Aussehen, um sich an die jeweilige Größe in Zellen anzupassen, wie in den folgenden Beispielen gezeigt.

Beispiel für ein Wetter-Widget in der kleinsten Größe (3 × 2). Auf der Benutzeroberfläche werden der Ortsname (Tokio), die Temperatur (14 °) 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 („mittel“). Beim Ändern der Größe des Widgets auf diese Weise wird die gesamte Benutzeroberfläche der vorherigen Widgetgröße übernommen und das Label „Meist bewölkt“ sowie eine Temperaturvorhersage für 16:00 bis 19:00 Uhr werden hinzugefügt.
Abbildung 3. 4 × 2 R.layout.widget_weather_forecast_medium.

Beispiel für ein Wetter-Widget in der Größe „Mittel“ (5 × 2). Wenn Sie die Größe des Widgets auf diese Weise ändern, wird die Benutzeroberfläche nicht verändert, sondern nur um eine Zelle in die Breite gezogen, sodass mehr horizontaler Platz zur Verfügung steht.
Abbildung 4. 5 × 2 R.layout.widget_weather_forecast_medium.

Beispiel für ein Wetter-Widget in der Größe „Groß“ (5 × 3). Beim Anpassen der Größe des Widgets auf diese Weise wird die gesamte Benutzeroberfläche der vorherigen Widget-Größen verwendet und dem Widget wird eine Ansicht mit einer Wettervorhersage für Dienstag und Mittwoch hinzugefügt. Symbole für sonniges oder regnerisches Wetter sowie 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 „groß“ (5 × 4). Beim Anpassen der Größe des Widgets auf diese Weise wird die gesamte Benutzeroberfläche der vorherigen Widget-Größen übernommen und es werden Donnerstag und Freitag (sowie die entsprechenden Symbole für den Wettertyp und die Höchst- und Tiefsttemperatur für jeden Tag) hinzugefügt.
Abbildung 6. 5 × 4 R.layout.widget_weather_forecast_large.