Android supporta un'ampia gamma di fattori di forma oltre ai tradizionali smartphone con orientamento verticale, tra cui pieghevoli, tablet, ambienti con finestre delle app e display esterni. Se presumi che la geometria dello schermo sia statica, i contenuti multimediali possono essere allungati, ritagliati o visualizzati involontariamente in formato letterbox. La tua app deve adattarsi dinamicamente alle diverse proporzioni dei contenuti multimediali di origine (dal classico 4:3 all'ultra-wide) nelle varie modalità di visualizzazione in evoluzione.
La maggior parte degli errori di layout dei contenuti multimediali in Jetpack Compose deriva da tre errori comuni di architettura:
- Gestione incoerente degli inset delle finestre e collisioni edge-to-edge.
- Aggiornamenti del layout incoerenti a causa di un calcolo errato delle dimensioni della finestra.
- Configurazione errata delle opzioni di scalabilità dei contenuti.
Questa guida illustra le strategie e le best practice per affrontare ciascuna di queste aree utilizzando Media3 e Jetpack Compose.
Gestisci gli inset delle finestre e le collisioni edge-to-edge
Sui dispositivi con Android 15 (livello API 35) e versioni successive, le app che hanno come target il livello API 35 o versioni successive vengono visualizzate in modalità edge-to-edge per impostazione predefinita. Le barre di sistema, come la barra di stato, la barra di navigazione e la barra del titolo della modalità desktop, vengono disegnate sopra i contenuti dell'app e i ritagli display possono oscurarne alcune parti.
Senza una corretta gestione degli inset della finestra, si verificano due principali conflitti di layout:
- Sovrapposizioni della barra di sistema: i fotogrammi video, i sottotitoli e i controlli di riproduzione sono parzialmente oscurati dalla barra di stato (orologio, icone della batteria), dalla barra di navigazione o dei gesti o dai ritagli display (notch della fotocamera). Per indicazioni generali sulla configurazione, consulta Configura la modalità edge-to-edge.
- Interferenza della barra del titolo in modalità desktop: in modalità finestre delle app, il sistema introduce una barra del titolo superiore per la gestione delle finestre. I layout standard che eseguono il rendering di intestazioni personalizzate o canvas multimediali edge-to-edge senza tenere conto di questa barra dei sottotitoli finiscono per avere i frame video e i controlli di riproduzione superiori oscurati e non selezionabili. Per maggiori dettagli sugli stati delle finestre, consulta Supporta le finestre delle app.
Strategie di gestione degli insetti
L'app deve adattarsi dinamicamente agli inset di sistema in base al fatto che il player sia in modalità non immersiva o immersiva.
Configurazioni non immersive
Nella riproduzione non immersiva, le barre di sistema rimangono visibili per preservare il contesto del dispositivo.
Quando il player si estende fino ai bordi della finestra, applica
windowInsetsPadding con
WindowInsets.safeDrawing e only a ogni
barra di controllo PlayerDefaults sui bordi in cui incontra le
barre di sistema o il ritaglio display (ad esempio, Top + Horizontal su TopControls
e Bottom + Horizontal su BottomControls). In questo modo, i controlli non vengono coperti dalle
barre di sistema, mentre la superficie del video si estende su tutto il container.
@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 ) ), ) }, ) }
Configurazioni immersive (verticale e orizzontale)
In modalità immersiva a schermo intero, l'obiettivo è massimizzare il canvas per un'esperienza cinematografica, mantenendo al contempo accessibili i controlli di riproduzione:
- Applica
windowInsetsPaddingagli overlay dei controlli multimediali (ad esempio i controlli in alto e in basso) per evitare che si sovrappongano ai ritagli display o alle aree dei gesti di sistema (ad esempio, combinandoWindowInsets.displayCutoutconWindowInsets.systemGesturessui controlli in basso in modo che la barra di scorrimento non entri in conflitto con i gesti di scorrimento dai bordi). - Nascondi le barre di sistema utilizzando
WindowInsetsControllerCompatall'interno di unDisposableEffect, assicurandoti che la visibilità della UI di sistema venga ripristinata quando esci dal composable.
@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) ), ) }, ) }
Calcola il dimensionamento dinamico della finestra e gli aggiornamenti del layout
Il calcolo della larghezza o dell'altezza dello schermo una sola volta all'avvio dell'app fa sì che i layout si basino su valori obsoleti quando la configurazione del dispositivo cambia, ad esempio quando un dispositivo pieghevole viene aperto, una sessione in modalità multi-finestra viene ridimensionata o il display viene ruotato.
In questi casi, anche se un componente secondario utilizza correttamente Modifier.fillMaxWidth(), non riuscirà ad adattarsi se il suo contenitore principale è limitato da dimensioni obsolete, causando allungamento, ritaglio o layout non adattabili.
Nell'esempio seguente, il frame a sinistra mostra il rendering corretto su una finestra visibile standard, mentre il frame a destra mostra l'errore di adattamento delle dimensioni della finestra obsolete quando un dispositivo viene aperto, con conseguente layout dei contenuti non adattabile.
Per evitare vincoli di layout obsoleti, utilizza l'API Jetpack Media Query. Poiché questa API è sperimentale e disabilitata per impostazione predefinita,
abilita prima la funzione mediaQuery impostando
ComposeUiFlags.isMediaQueryIntegrationEnabled = true (ad esempio, prima di
chiamare setContent) e attiva
@OptIn(ExperimentalMediaQueryApi::class).
Utilizza derivedMediaQuery per valutare le condizioni in base alle dimensioni della finestra corrente, ad esempio windowWidth, in modo che il layout venga aggiornato quando la finestra cambia senza ricomposizioni non necessarie. Puoi combinare
derivedMediaQuery con i breakpoint WindowSizeClass per
passare dai layout del player a riquadro singolo a quelli a più riquadri man mano che la finestra si espande:
@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() } } } }
Configura la scalabilità dei contenuti e le proporzioni
Distinguere tra la gestione dell'area del container disponibile e la scalabilità dei contenuti multimediali stessi. Utilizza la gestione degli inset, ad esempio il padding dell'area sicura, per impostare i confini del contenitore in relazione alle barre di sistema e ai ritagli display. Quindi, applica le strategie di scalabilità entro questi limiti. Per indicazioni di progettazione sulla strutturazione dei contenitori e sulla scalabilità dei contenuti visivi in base ai vari formati, consulta Composizione e struttura dei contenuti.
Nell'esempio seguente, l'immagine a sinistra mostra come una strategia di ritaglio può tagliare i contenuti quando è richiesta la visibilità completa, mentre l'immagine a destra mostra come una strategia di adattamento preserva le proporzioni native per il rendering a frame intero.
I componenti Media3 gestiscono automaticamente le proporzioni video standard, ma le configurazioni esplicite di ContentScale diventano fondamentali quando si lavora con layout Compose personalizzati o container vincolati (come i feed social scorrevoli). La selezione di una scala dei contenuti non corretta può causare problemi di layout, come la distorsione del video (allungamento) o un letterbox involontario che lascia spazio vuoto nell'area visibile. La gestione manuale delle superfici video senza queste opzioni può anche comportare layout non funzionanti durante le rotazioni dello schermo o i cambi di stato dei dispositivi pieghevoli.
Sia che venga visualizzato un video 16:9 su uno schermo 4:3 o un video 4:3 su un display 16:9, il composable Player utilizza per impostazione predefinita ContentScale.Fit. In questo modo, l'intero video rimane visibile senza ritagli, applicando il letterbox o il pillarbox.
Le successive modifiche alla modalità di visualizzazione (come lo zoom o il ritaglio) devono essere
eseguite dall'utente. Ad esempio, passa a ContentScale.Crop per riempire completamente il contenitore. Un pulsante di attivazione/disattivazione interattivo per la scalabilità bilancia i requisiti di layout con la scelta dell'utente.
Implementazioni di esempio
Puoi applicare la visibilità a schermo intero e gestire le proporzioni utilizzando le proprietà standard di Compose ContentScale.
Utilizza il composable Player
L'approccio più semplice e diretto è utilizzare il componibile Player. Funge da wrapper di alto livello che gestisce automaticamente i limiti di scalabilità, accoppia un ContentFrame per il rendering dei video con overlay di controllo personalizzabili (topControls, centerControls, bottomControls) e un livello di otturatore:
@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 ) }
Quando crei un layout del video player personalizzato o posizioni livelli UI personalizzati direttamente sopra lo stream video, puoi utilizzare ContentFrame direttamente per un controllo del layout preciso e di livello inferiore.
Pulsante di attivazione/disattivazione della scalabilità dinamica controllata dall'utente
Per migliorare l'esperienza di visualizzazione della tua app, puoi aggiungere un pulsante di attivazione/disattivazione facoltativo per passare da un'opzione di scalabilità dei contenuti all'altra. Rilevando un gesto di doppio tocco, puoi passare istantaneamente dallo stato ContentScale.Fit allo stato ContentScale.Crop del player. Puoi anche estendere questa funzionalità per supportare le regolazioni dinamiche di ContentScale utilizzando il gesto di pizzicare per eseguire lo zoom o altri gesti multi-touch, in modo simile alle moderne applicazioni di streaming video.
@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, ) }
Sebbene esistano diverse opzioni di scalabilità dei contenuti, scegli l'opzione di scalabilità in base al tuo caso d'uso: utilizza ContentScale.Crop per i video nel formato breve o i feed scorrevoli in cui l'obiettivo principale è riempire lo schermo e imposta come predefinita l'opzione ContentScale.Fit per i contenuti multimediali con informazioni importanti sui margini, come i punteggi sportivi o i sottotitoli, per salvaguardare il contesto visivo essenziale.