Scala i contenuti multimediali su più fattori di forma

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.
Barra di stato del sistema che si sovrappone al canvas multimediale edge-to-edge e ai controlli di riproduzione. Barra di navigazione tramite gesti che si sovrappone al canvas multimediale edge-to-edge. Barra dei sottotitoli su computer che si sovrappone ai controlli di riproduzione video in alto.
Figura 1. La barra di stato del sistema, la barra di navigazione tramite gesti e la barra dei sottotitoli del desktop si sovrappongono al canvas multimediale edge-to-edge e oscurano i contenuti video e i controlli di riproduzione.

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

In modalità non immersiva, l'app integra il padding degli inset della finestra per spostare dinamicamente i contenuti verso l'interno.
Figura 2. In modalità non immersiva, l'app applica il padding degli inset della finestra per spostare i controlli verso l'interno.

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:

  1. Applica windowInsetsPadding agli 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, combinando WindowInsets.displayCutout con WindowInsets.systemGestures sui controlli in basso in modo che la barra di scorrimento non entri in conflitto con i gesti di scorrimento dai bordi).
  2. Nascondi le barre di sistema utilizzando WindowInsetsControllerCompat all'interno di un DisposableEffect, 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)
            ),
      )
    },
  )
}

La barra di sistema si nasconde automaticamente quando il video player entra in modalità immersiva, offrendo un'esperienza cinematografica a schermo intero.
Figura 3. Le barre di sistema vengono nascoste quando il video player entra in modalità immersiva.

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.

Rendering corretto nell'area visibile standard con adattamento dinamico delle proporzioni. Mancato adattamento delle dimensioni della finestra obsolete quando il dispositivo viene aperto.
Figura 4. Confronto dell'adattamento dinamico delle proporzioni.

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.

Strategia di ritaglio che causa una perdita significativa di contenuti quando è richiesta la visibilità completa. Strategia di adattamento che mantiene le proporzioni native per il rendering a schermo intero.
Figura 5. Confronto dei comportamenti di scalabilità.

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.

Figura 6. Passaggio da ContentScale.Fit a 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,
  )
}

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.