Media-Inhalte für verschiedene Formfaktoren skalieren

Android unterstützt eine Vielzahl von Formfaktoren, die über herkömmliche Smartphones im Hochformat hinausgehen, darunter faltbare Smartphones, Tablets, Desktop-Freiform-Fenster und externe Displays. Wenn du davon ausgehst, dass die Bildschirmgeometrie statisch ist, können Medieninhalte gestreckt, zugeschnitten oder unbeabsichtigt mit Letterbox-Effekt dargestellt werden. Ihre App muss sich dynamisch an verschiedene Seitenverhältnisse der Quellmedien (vom klassischen 4:3 bis zum Ultrawide-Format) in verschiedenen Anzeigemodi anpassen.

Die meisten Fehler bei Medienlayouts in Jetpack Compose sind auf drei häufige Architekturprobleme zurückzuführen:

  • Inkonsistente Verarbeitung von Fenster-Insets und Edge-to-Edge-Kollisionen.
  • Inkonsistente Layoutaktualisierungen aufgrund einer falschen Berechnung der Fenstergröße.
  • Falsche Konfiguration der Optionen für die Inhaltsskalierung.

In diesem Leitfaden werden Strategien und Best Practices für die einzelnen Bereiche mit Media3 und Jetpack Compose beschrieben.

Fenster-Insets und Edge-to-Edge-Kollisionen verarbeiten

Auf Geräten mit Android 15 (API-Level 35) und höher werden Apps, die auf API-Level 35 oder höher ausgerichtet sind, standardmäßig randlos angezeigt. Systemleisten wie die Statusleiste, die Navigationsleiste und die Titelleiste des Desktops werden über den Inhalten Ihrer App angezeigt. Display-Aussparungen können Teile davon verdecken.

Ohne eine ordnungsgemäße Verwaltung von Fenster-Insets treten zwei wesentliche Layoutkonflikte auf:

  • Überlappungen mit Systemleisten: Videoframes, Untertitel und Wiedergabesteuerungen werden teilweise von der Statusleiste (Uhr, Akkusymbole), der Gesten- oder Navigationsleiste oder Display-Aussparungen (Kamera-Notches) verdeckt. Eine allgemeine Anleitung zur Einrichtung finden Sie unter Edge-to-Edge-Modus einrichten.
  • Störungen durch die Titelleiste im Desktopmodus: Im Desktop-Freiform-Fenster-Modus wird eine obere Titelleiste für die Fensterverwaltung eingeführt. Bei Standardlayouts, die benutzerdefinierte Header oder randlose Medien-Canvases rendern, ohne diese Untertitelleiste zu berücksichtigen, werden Videoframes und die oberen Wiedergabesteuerelemente verdeckt und können nicht angeklickt werden. Weitere Informationen zu Fensterstatus finden Sie unter Desktop-Freiform-Fenster unterstützen.
Die Systemstatusleiste überlappt den randlosen Medien-Canvas und die Wiedergabesteuerung. Die Navigationsleiste für die Bedienung über Gesten überlappt den Medienbereich, der das gesamte Display einnimmt. Die Untertitelleiste auf dem Computer überlappt die oberen Steuerelemente für die Videowiedergabe.
Abbildung 1. Die Systemstatusleiste, die Navigationsleiste für die Bedienung über Gesten und die Titelleiste im Desktopmodus überlappen den randlosen Medienbereich und verdecken Videoinhalte und die Wiedergabesteuerung.

Strategien für die Verwaltung von Insets

Deine App sollte sich dynamisch an die System-Insets anpassen, je nachdem, ob sich der Spieler im nicht immersiven oder immersiven Modus befindet.

Nicht immersive Konfigurationen

Bei der nicht immersiven Wiedergabe bleiben die Systemleisten sichtbar, um den Gerätekontext beizubehalten.

Wenn der Player bis zu den Fensterrändern reicht, wende windowInsetsPadding mit WindowInsets.safeDrawing und only auf jede PlayerDefaults-Steuerleiste an den Rändern an, an denen sie auf die Systemleisten oder die Display-Aussparung trifft (z. B. Top + Horizontal auf TopControls und Bottom + Horizontal auf BottomControls). Dadurch werden die Steuerelemente von den Systemleisten ferngehalten, während sich die Videooberfläche über den Container erstreckt.

@Composable
fun NonImmersiveVideoPlayer(
  player: Player,
  showControls: Boolean,
  modifier: Modifier = Modifier,
) {
  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the status bar, caption bar, and display cutout
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(WindowInsetsSides.Top + WindowInsetsSides.Horizontal)
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the navigation bar and display cutout
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(
                WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal
              )
            ),
      )
    },
  )
}

Im nicht immersiven Modus wird in der App ein Fenster-Inset-Padding verwendet, um Inhalte dynamisch nach innen zu verschieben.
Abbildung 2: Im nicht immersiven Modus wendet die App ein Padding für Fenstereinsätze an, um die Steuerelemente nach innen zu verschieben.

Immersive Konfigurationen (Hoch- und Querformat)

Im immersiven Vollbildmodus soll die Leinwand für ein kinoähnliches Erlebnis maximiert werden, während die Wiedergabesteuerung zugänglich bleibt:

  1. Wende windowInsetsPadding auf Overlays für die Mediensteuerung an (z. B. Steuerelemente oben und unten), um zu verhindern, dass sie Display-Aussparungen oder Bereiche für System-Gesten überlappen. Du kannst beispielsweise WindowInsets.displayCutout mit WindowInsets.systemGestures für die Steuerelemente unten kombinieren, damit die Steuerleiste nicht mit Wischgesten am Rand kollidiert.
  2. Blende Systemleisten mit WindowInsetsControllerCompat in einem DisposableEffect aus, damit die Sichtbarkeit der System-UI wiederhergestellt wird, wenn du das Composable verlässt.

@Composable
fun ImmersiveVideoPlayer(player: Player, showControls: Boolean, modifier: Modifier = Modifier) {
  val view = LocalView.current

  // Manages the system UI lifecycle to create an edge-to-edge cinematic experience
  DisposableEffect(view) {
    // Finds the hosting Activity, unwrapping any ContextWrapper around the view's context
    val activity =
      generateSequence(view.context) { (it as? ContextWrapper)?.baseContext }
        .filterIsInstance<Activity>()
        .firstOrNull()
    val window = activity?.window ?: return@DisposableEffect onDispose {}
    val controller = WindowCompat.getInsetsController(window, view)

    // Records the current system bar state so it can be restored on dispose
    val insets = ViewCompat.getRootWindowInsets(view)
    val wereSystemBarsVisible =
      insets == null ||
        insets.isVisible(WindowInsetsCompat.Type.statusBars()) ||
        insets.isVisible(WindowInsetsCompat.Type.navigationBars())
    val previousBehavior = controller.systemBarsBehavior

    // Hides status bars, navigation bars, and caption bars to maximize the video canvas
    controller.hide(WindowInsetsCompat.Type.systemBars())

    // Allows hidden system bars to temporarily reappear with a swipe gesture from the edge
    controller.systemBarsBehavior =
      WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

    onDispose {
      // Restores the previous system bar state when leaving the composable
      controller.systemBarsBehavior = previousBehavior
      if (wereSystemBarsVisible) {
        controller.show(WindowInsetsCompat.Type.systemBars())
      }
    }
  }

  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the display cutout while the system bars are hidden
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout.only(
                WindowInsetsSides.Top + WindowInsetsSides.Horizontal
              )
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the display cutout and system gesture areas
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout
                .union(WindowInsets.systemGestures)
                .only(WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal)
            ),
      )
    },
  )
}

Die Systemleiste wird automatisch ausgeblendet, wenn der Videoplayer in den immersiven Modus wechselt, um ein Vollbild-Kinoerlebnis zu bieten.
Abbildung 3: Die Systemleisten werden ausgeblendet, wenn der Videoplayer in den immersiven Modus wechselt.

Dynamische Fenstergröße und Layoutaktualisierungen berechnen

Wenn die Bildschirmbreite oder -höhe nur einmal beim Start der App berechnet wird, basieren Layouts auf veralteten Werten, wenn sich die Gerätekonfiguration ändert, z. B. wenn ein faltbares Gerät aufgeklappt, die Größe einer Sitzung im Mehrfenstermodus geändert oder das Display gedreht wird.

In diesen Fällen kann sich eine untergeordnete Komponente, selbst wenn sie Modifier.fillMaxWidth() korrekt verwendet, nicht anpassen, wenn ihr übergeordneter Container durch veraltete Abmessungen eingeschränkt ist. Dies führt zu Dehnung, Abschneiden oder nicht responsiven Layouts.

Im folgenden Beispiel zeigt der linke Frame die korrekte Darstellung in einem Standard-Viewport, während der rechte Frame zeigt, dass sich veraltete Fensterabmessungen nicht anpassen, wenn ein Gerät aufgeklappt wird. Das führt zu einem nicht responsiven Inhaltslayout.

Korrekte Darstellung im Standard-Darstellungsbereich mit dynamischer Anpassung des Seitenverhältnisses. Fehler beim Anpassen veralteter Fensterabmessungen, wenn das Gerät aufgeklappt wird.
Abbildung 4. Vergleich der dynamischen Anpassung des Seitenverhältnisses.

Verwenden Sie die Jetpack Medienabfrage API, um veraltete Layoutbeschränkungen zu vermeiden. Da diese API experimentell und standardmäßig deaktiviert ist, müssen Sie zuerst die Funktion mediaQuery aktivieren. Legen Sie dazu ComposeUiFlags.isMediaQueryIntegrationEnabled = true fest (z. B. vor dem Aufruf von setContent) und aktivieren Sie die Funktion mit @OptIn(ExperimentalMediaQueryApi::class).

Verwenden Sie derivedMediaQuery, um Bedingungen für die aktuelle Fenstergröße wie windowWidth auszuwerten, damit Ihr Layout bei Änderungen des Fensters ohne unnötige Neuzusammensetzungen aktualisiert wird. Sie können derivedMediaQuery mit WindowSizeClass-Haltepunkten kombinieren, um zwischen Player-Layouts mit einem oder mehreren Bereichen zu wechseln, wenn das Fenster vergrößert wird:

@OptIn(ExperimentalMediaQueryApi::class)
@Composable
fun AdaptiveVideoPlayerScreen(
  player: Player,
  modifier: Modifier = Modifier,
  relatedContent: @Composable () -> Unit,
) {
  val isWideWindow by derivedMediaQuery {
    windowWidth >= WindowSizeClass.WIDTH_DP_MEDIUM_LOWER_BOUND.dp
  }

  if (isWideWindow) {
    // Medium or expanded width: place the player alongside a details or playlist pane
    Row(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.weight(0.65f).fillMaxHeight())
      Box(modifier = Modifier.weight(0.35f).fillMaxHeight()) { relatedContent() }
    }
  } else {
    // Compact width: stack a 16:9 player above the details pane
    Column(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.fillMaxWidth().aspectRatio(16f / 9f))
      Box(modifier = Modifier.weight(1f).fillMaxWidth()) { relatedContent() }
    }
  }
}

Inhaltsskalierung und Seitenverhältnisse konfigurieren

Unterscheiden Sie zwischen der Verwaltung des verfügbaren Containerbereichs und der Skalierung des Medieninhalts selbst. Verwenden Sie die Inset-Verwaltung, z. B. Safe-Area-Padding, um Containergrenzen relativ zu Systemleisten und Display-Aussparungen festzulegen. Wenden Sie dann Skalierungsstrategien innerhalb dieser Grenzen an. Designhinweise zur Strukturierung von Containern und zur Skalierung visueller Inhalte über verschiedene Seitenverhältnisse hinweg finden Sie unter Inhaltskomposition und -struktur.

Im folgenden Beispiel zeigt das linke Bild, wie durch eine Zuschneidestrategie Inhalte abgeschnitten werden können, wenn eine vollständige Sichtbarkeit erforderlich ist. Das rechte Bild zeigt, wie durch eine Anpassungsstrategie das native Seitenverhältnis für das Rendern im Vollbildmodus beibehalten wird.

Die Zuschneidestrategie führt zu einem erheblichen Inhaltsverlust, wenn eine vollständige Sichtbarkeit erforderlich ist. Anpassungsstrategie, bei der das native Seitenverhältnis für das Vollbild-Rendering beibehalten wird.
Abbildung 5. Vergleich des Skalierungsverhaltens.

Media3-Komponenten verarbeiten Standard-Seitenverhältnisse von Videos automatisch. Explizite ContentScale-Konfigurationen sind jedoch wichtig, wenn Sie mit benutzerdefinierten Compose-Layouts oder eingeschränkten Containern (z. B. scrollbaren Social-Media-Feeds) arbeiten. Die Auswahl einer ungeeigneten Inhaltsskalierung kann zu Layoutproblemen führen, z. B. zu Videoverzerrungen (Streckung) oder unbeabsichtigtem Letterboxing, bei dem leerer Platz im Darstellungsbereich bleibt. Wenn Sie Videooberflächen manuell ohne diese Optionen verwalten, kann es auch zu fehlerhaften Layouts kommen, wenn der Bildschirm gedreht wird oder sich der Status eines faltbaren Geräts ändert.

Unabhängig davon, ob ein 16:9-Video auf einem 4:3-Bildschirm oder ein 4:3-Video auf einem 16:9-Display angezeigt wird, wird für das Player-Composable standardmäßig ContentScale.Fit verwendet. So bleibt das gesamte Video sichtbar, ohne dass es durch Letterboxing oder Pillarboxing beschnitten wird.

Nachfolgende Änderungen des Anzeigemodus (z. B. Zoomen oder Zuschneiden) sollten vom Nutzer vorgenommen werden. Wechseln Sie beispielsweise zu ContentScale.Crop, um den Container vollständig zu füllen. Ein interaktiver Skalierungsschalter sorgt für ein ausgewogenes Verhältnis zwischen Layoutanforderungen und Nutzerauswahl.

Implementierungsbeispiele

Mit den Standard-ContentScale-Eigenschaften von Compose können Sie die Sichtbarkeit des gesamten Frames erzwingen und Seitenverhältnisse verwalten.

Das Composeable Player verwenden

Der einfachste und direkteste Ansatz ist die Verwendung des Composeables Player. Er dient als übergeordneter Wrapper, der Skalierungsgrenzen automatisch verarbeitet, und kombiniert eine ContentFrame für das Videorendering mit anpassbaren Steuerungsoverlays (topControls, centerControls, bottomControls) und einer Verschlussebene:

@Composable
fun FitVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  Player(
    player = player,
    modifier = modifier.fillMaxSize(), // Fill the available space
    contentScale = ContentScale.Fit, // Default; shown for clarity
  )
}

Wenn Sie ein benutzerdefiniertes Videoplayer-Layout erstellen oder benutzerdefinierte UI-Ebenen direkt über dem Videostream platzieren, können Sie ContentFrame direkt für eine präzise, detaillierte Layoutsteuerung verwenden.

Ein/Aus-Button für die dynamische nutzergesteuerte Skalierung

Wenn du die Wiedergabe in deiner App verbessern möchtest, kannst du einen optionalen Schalter hinzufügen, mit dem Nutzer zwischen verschiedenen Optionen für die Skalierung von Inhalten wechseln können. Wenn du eine Doppeltipp-Geste erkennst, kannst du den Status des Players sofort zwischen ContentScale.Fit und ContentScale.Crop umschalten. Sie können diese Funktion auch erweitern, um dynamische ContentScale-Anpassungen mit Multitouch-Gesten wie „Auseinander- und Zusammenziehen“ zu unterstützen, ähnlich wie bei modernen Videostreaming-Anwendungen.

Abbildung 6. Wechsel zwischen ContentScale.Fit und ContentScale.Crop.

@Composable
fun ZoomableVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  var isCropped by rememberSaveable { mutableStateOf(false) }

  Player(
    player = player,
    modifier =
      modifier
        .fillMaxSize()
        // Handle double-tap to toggle between Fit and Crop scaling
        .pointerInput(Unit) { detectTapGestures(onDoubleTap = { isCropped = !isCropped }) },
    contentScale = if (isCropped) ContentScale.Crop else ContentScale.Fit,
  )
}

Es gibt mehrere Optionen für die Skalierung von Inhalten. Wählen Sie die Skalierungsoption basierend auf Ihrem Anwendungsfall aus: Verwenden Sie ContentScale.Crop für Kurzvideos oder scrollbare Feeds, bei denen das Ausfüllen des Bildschirms das Hauptziel ist, und verwenden Sie standardmäßig ContentScale.Fit für Medien mit wichtigen Informationen am Rand, z. B. Sportergebnisse oder Untertitel, um den wichtigen visuellen Kontext zu erhalten.