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

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:
- Wende
windowInsetsPaddingauf 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 beispielsweiseWindowInsets.displayCutoutmitWindowInsets.systemGesturesfür die Steuerelemente unten kombinieren, damit die Steuerleiste nicht mit Wischgesten am Rand kollidiert. - Blende Systemleisten mit
WindowInsetsControllerCompatin einemDisposableEffectaus, 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) ), ) }, ) }
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.
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.
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.
@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.