Adapter le contenu multimédia à différents facteurs de forme

Android est compatible avec un large éventail de facteurs de forme, au-delà des smartphones classiques en mode Portrait, y compris les appareils pliables, les tablettes, les environnements de fenêtrage du bureau et les écrans externes. Si vous supposez que la géométrie de l'écran est statique, le contenu multimédia peut se retrouver étiré, recadré ou involontairement au format letterbox. Votre application doit s'adapter de manière dynamique aux différents formats de sources multimédias (du format 4:3 classique au format ultra-large) dans les différents modes d'affichage.

La plupart des échecs de mise en page multimédia dans Jetpack Compose proviennent de trois écueils architecturaux courants :

  • Gestion incohérente des encarts de fenêtre et des collisions de bord à bord.
  • Mises à jour de la mise en page incohérentes en raison d'un calcul incorrect de la taille de la fenêtre.
  • Mauvaise configuration des options de scaling du contenu.

Ce guide présente les stratégies et les bonnes pratiques pour aborder chacun de ces domaines à l'aide de Media3 et de Jetpack Compose.

Gérer les encarts de fenêtre et les collisions bord à bord

Sur les appareils équipés d'Android 15 (niveau d'API 35) ou version ultérieure, les applications qui ciblent le niveau d'API 35 ou version ultérieure sont affichées de bord à bord par défaut. Les barres système telles que la barre d'état, la barre de navigation et la barre de légende de l'ordinateur s'affichent par-dessus le contenu de votre application, et les encoches peuvent en masquer certaines parties.

Sans une gestion appropriée des encarts de fenêtre, deux conflits de mise en page majeurs se produisent :

  • Chevauchements de la barre système : les images vidéo, les sous-titres et les commandes de lecture sont partiellement masqués par la barre d'état (horloge, icônes de batterie), la barre de navigation ou de gestes, ou les découpes de l'écran (encoches de l'appareil photo). Pour obtenir des conseils de configuration généraux, consultez Configurer l'affichage bord à bord.
  • Interférence de la barre de légende en mode ordinateur : en mode fenêtrage du bureau, le système introduit une barre de légende supérieure pour la gestion des fenêtres. Les mises en page standards qui affichent des en-têtes personnalisés ou des canevas multimédias bord à bord sans tenir compte de cette barre de sous-titres se retrouvent avec des images vidéo et des commandes de lecture supérieures masquées et non cliquables. Pour en savoir plus sur les états de fenêtre, consultez Prendre en charge le fenêtrage du bureau.
Barre d'état du système chevauchant le canevas multimédia de bord à bord et les commandes de lecture. La barre de navigation par gestes chevauche le canevas multimédia bord à bord. La barre de sous-titres sur ordinateur chevauche les commandes de lecture vidéo supérieures.
Figure 1. La barre d'état du système, la barre de navigation par gestes et la barre de légende du bureau se superposent au canevas multimédia de bord à bord, et masquent le contenu vidéo et les commandes de lecture.

Stratégies de gestion des encarts

Votre application doit s'adapter de manière dynamique aux encarts système selon que le lecteur est en mode immersif ou non.

Configurations non immersives

En lecture non immersive, les barres système restent visibles pour préserver le contexte de l'appareil.

Lorsque le lecteur s'étend jusqu'aux bords de la fenêtre, appliquez windowInsetsPadding avec WindowInsets.safeDrawing et only à chaque barre de contrôle PlayerDefaults sur les bords où elle rencontre les barres système ou l'encoche de l'écran (par exemple, Top + Horizontal sur TopControls et Bottom + Horizontal sur BottomControls). Cela permet de ne pas encombrer les barres système avec les commandes, tandis que la surface vidéo s'étend sur l'ensemble du conteneur.

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

En mode non immersif, l'application intègre une marge intérieure d'encart de fenêtre pour décaler dynamiquement le contenu vers l'intérieur.
Figure 2. En mode non immersif, l'application applique une marge intérieure d'encart de fenêtre pour décaler les commandes vers l'intérieur.

Configurations immersives (portrait et paysage)

En mode immersif plein écran, l'objectif est de maximiser le canevas pour une expérience cinématographique tout en gardant les commandes de lecture accessibles :

  1. Appliquez windowInsetsPadding aux superpositions de commandes multimédias (telles que les commandes supérieures et inférieures) pour éviter qu'elles ne chevauchent les découpes d'écran ou les zones de gestes système (par exemple, en combinant WindowInsets.displayCutout avec WindowInsets.systemGestures sur les commandes inférieures afin que la barre de recherche n'entre pas en conflit avec les gestes de balayage des bords).
  2. Masquez les barres système à l'aide de WindowInsetsControllerCompat dans un DisposableEffect, en veillant à ce que la visibilité de l'UI du système soit restaurée lorsque vous quittez le 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 barre système se masque automatiquement lorsque le lecteur vidéo passe en mode immersif, offrant ainsi une expérience cinématographique en plein écran.
Figure 3. Les barres système sont masquées lorsque le lecteur vidéo passe en mode immersif.

Calculer le dimensionnement dynamique des fenêtres et les mises à jour de la mise en page

Si la largeur ou la hauteur de l'écran ne sont calculées qu'une seule fois au démarrage de l'application, les mises en page s'appuient sur des valeurs obsolètes lorsque la configuration de l'appareil change (par exemple, lorsqu'un appareil pliable est déplié, qu'une session en mode multifenêtre est redimensionnée ou que l'écran pivote).

Dans ce cas, même si un composant enfant utilise correctement Modifier.fillMaxWidth(), il ne s'adaptera pas si son conteneur parent est limité par des dimensions obsolètes, ce qui entraîne un étirement, un rognage ou des mises en page non responsives.

Dans l'exemple suivant, l'image de gauche illustre l'affichage correct sur une fenêtre d'affichage standard, tandis que l'image de droite montre l'échec de l'adaptation des dimensions de la fenêtre obsolète lorsqu'un appareil est déplié, ce qui entraîne une mise en page non responsive du contenu.

Rendu correct sur une fenêtre d'affichage standard avec adaptation dynamique du format. Échec de l'adaptation des dimensions de la fenêtre obsolète lorsque l'appareil est déplié.
Figure 4. Comparaison de l'adaptation dynamique du format.

Pour éviter les contraintes de mise en page obsolètes, utilisez l'API Jetpack Media Query. Comme cette API est expérimentale et désactivée par défaut, commencez par activer la fonction mediaQuery en définissant ComposeUiFlags.isMediaQueryIntegrationEnabled = true (par exemple, avant d'appeler setContent), puis activez-la avec @OptIn(ExperimentalMediaQueryApi::class).

Utilisez derivedMediaQuery pour évaluer les conditions de la taille de la fenêtre actuelle, comme windowWidth, afin que votre mise en page soit mise à jour lorsque la fenêtre change, sans recompositions inutiles. Vous pouvez combiner derivedMediaQuery avec des points d'arrêt WindowSizeClass pour basculer entre les mises en page de lecteur à un ou plusieurs volets à mesure que la fenêtre s'agrandit :

@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() }
    }
  }
}

Configurer la mise à l'échelle du contenu et les formats

Faites la distinction entre la gestion de la zone de conteneur disponible et le scaling du contenu multimédia lui-même. Utilisez la gestion des encarts, comme la marge intérieure de la zone de sécurité, pour définir les limites du conteneur par rapport aux barres système et aux encoches de l'écran. Ensuite, appliquez des stratégies de scaling dans ces limites. Pour obtenir des conseils de conception sur la structuration des conteneurs et la mise à l'échelle du contenu visuel en fonction des formats, consultez Composition et structure du contenu.

Dans l'exemple suivant, l'image de gauche montre comment une stratégie de recadrage peut couper du contenu lorsque la visibilité complète est requise, tandis que l'image de droite montre comment une stratégie d'ajustement préserve le format natif pour un rendu plein écran.

La stratégie de recadrage entraîne une perte de contenu importante lorsqu'une visibilité complète est requise. Stratégie d'ajustement conservant le format natif pour un rendu plein écran.
Figure 5 : Comparaison des comportements de scaling.

Les composants Media3 gèrent automatiquement les formats vidéo standards, mais les configurations ContentScale explicites deviennent essentielles lorsque vous travaillez avec des mises en page Compose personnalisées ou des conteneurs limités (comme les flux de réseaux sociaux à défilement). La sélection d'une échelle de contenu incorrecte peut entraîner des problèmes de mise en page, tels qu'une distorsion de la vidéo (étirement) ou un format letterbox involontaire qui laisse un espace vide dans la fenêtre d'affichage. La gestion manuelle des surfaces vidéo sans ces options peut également entraîner des problèmes de mise en page lors de la rotation de l'écran ou des changements d'état des appareils pliables.

Qu'il s'agisse d'afficher une vidéo 16:9 sur un écran 4:3 ou une vidéo 4:3 sur un écran 16:9, le composable Player est défini par défaut sur ContentScale.Fit. Cela permet de garder l'intégralité de la vidéo visible sans la recadrer, en appliquant un format letterbox ou pillarbox.

Les modifications ultérieures du mode d'affichage (comme le zoom ou le recadrage) doivent être effectuées par l'utilisateur. Par exemple, passez à ContentScale.Crop pour remplir complètement le conteneur. Un bouton d'activation/désactivation interactif de la mise à l'échelle permet de trouver un équilibre entre les exigences de mise en page et le choix utilisateur.

Exemples de mise en œuvre

Vous pouvez appliquer la visibilité plein cadre et gérer les formats à l'aide des propriétés ContentScale standards de Compose.

Utiliser le composable Player

L'approche la plus simple et la plus directe consiste à utiliser le composable Player. Il s'agit d'un wrapper de haut niveau qui gère automatiquement les limites de mise à l'échelle. Il associe un ContentFrame pour l'affichage vidéo à des superpositions de commandes personnalisables (topControls, centerControls, bottomControls) et à une couche d'obturateur :

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

Lorsque vous créez une mise en page de lecteur vidéo personnalisée ou que vous placez des couches d'interface utilisateur personnalisées directement sur le flux vidéo, vous pouvez utiliser ContentFrame directement pour un contrôle précis de la mise en page de niveau inférieur.

Bouton d'activation/désactivation du scaling dynamique contrôlé par l'utilisateur

Pour améliorer l'expérience de visionnage de votre application, vous pouvez ajouter un bouton d'activation/de désactivation facultatif permettant de basculer entre différentes options de mise à l'échelle du contenu. En détectant un geste d'appui deux fois, vous pouvez basculer instantanément l'état du lecteur entre ContentScale.Fit et ContentScale.Crop. Vous pouvez également étendre cette fonctionnalité pour permettre des ajustements dynamiques de ContentScale à l'aide du zoom par pincement ou d'autres gestes à plusieurs doigts, comme dans les applications de streaming vidéo modernes.

Figure 6. Passage de ContentScale.Fit à 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,
  )
}

Bien qu'il existe plusieurs options de mise à l'échelle du contenu, choisissez l'option de mise à l'échelle en fonction de votre cas d'utilisation : utilisez ContentScale.Crop pour les vidéos courtes ou les flux à défilement où l'objectif principal est de remplir l'écran, et utilisez par défaut ContentScale.Fit pour les contenus multimédias contenant des informations importantes sur les marges, comme les scores sportifs ou les sous-titres, afin de préserver le contexte visuel essentiel.