Android potencia una amplia variedad de factores de forma más allá de los smartphones verticales convencionales, incluidos los dispositivos plegables, las tablets, los entornos de ventanas de escritorio y las pantallas externas. Si asumes que la geometría de la pantalla es estática, el contenido multimedia puede terminar estirado, recortado o con formato letterbox no deseado. Tu app debe adaptarse de forma dinámica a las distintas relaciones de aspecto de los medios de origen (desde la clásica de 4:3 hasta la ultraancha) en los diferentes modos de visualización.
La mayoría de las fallas de diseño de contenido multimedia en Jetpack Compose se deben a tres errores comunes de arquitectura:
- Control de inserciones de ventanas inconsistente y colisiones de borde a borde
- Actualizaciones de diseño incoherentes debido a un cálculo incorrecto del tamaño de la ventana
- Configuración incorrecta de las opciones de escalamiento de contenido
En esta guía, se abordan estrategias y prácticas recomendadas para abordar cada una de estas áreas con Media3 y Jetpack Compose.
Cómo controlar las inserciones de ventanas y las colisiones de borde a borde
En los dispositivos que ejecutan Android 15 (nivel de API 35) y versiones posteriores, las apps que se orientan al nivel de API 35 o versiones posteriores se muestran de borde a borde de forma predeterminada. Las barras del sistema, como la barra de estado, la barra de navegación y la barra de subtítulos de escritorio, se dibujan sobre el contenido de tu app, y los cortes de pantalla pueden ocultar partes de él.
Sin una administración adecuada de las inserciones de ventanas, se producen dos conflictos de diseño importantes:
- Superposiciones de la barra del sistema: Los fotogramas, los subtítulos y los controles de reproducción están parcialmente ocultos por la barra de estado (íconos de reloj y batería), la barra de navegación o de gestos, o los cortes de pantalla (muescas de la cámara). Para obtener orientación general sobre la configuración, consulta Cómo configurar el diseño de borde a borde.
- Interferencia de la barra de subtítulos del modo de escritorio: En el modo de ventanas de escritorio, el sistema introduce una barra de subtítulos superior para la administración de ventanas. Los diseños estándar que renderizan encabezados personalizados o lienzos multimedia de borde a borde sin tener en cuenta esta barra de subtítulos terminan con fotogramas y controles de reproducción superiores ocultos y en los que no se puede hacer clic. Para obtener más detalles sobre los estados de las ventanas, consulta Cómo admitir el modo de ventanas de escritorio.
Estrategias de administración de inserciones
Tu app debería adaptarse de forma dinámica a las inserciones del sistema según si el reproductor está en modo envolvente o no.
Parámetros de configuración no envolventes
En la reproducción no envolvente, las barras del sistema permanecen visibles para preservar el contexto del dispositivo.
Cuando el reproductor se extienda hasta los bordes de la ventana, aplica windowInsetsPadding con WindowInsets.safeDrawing y only a cada barra de control PlayerDefaults en los bordes donde se une con las barras del sistema o el corte de pantalla (por ejemplo, Top + Horizontal en TopControls y Bottom + Horizontal en BottomControls). Esto mantiene los controles alejados de las barras del sistema mientras la superficie de video se extiende por el contenedor.
@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 ) ), ) }, ) }
Configuraciones envolventes (vertical y horizontal)
En el modo envolvente de pantalla completa, el objetivo es maximizar el lienzo para obtener una experiencia cinematográfica y, al mismo tiempo, mantener accesibles los controles de reproducción:
- Aplica
windowInsetsPaddinga las superposiciones de controles multimedia (como los controles superiores e inferiores) para evitar que se superpongan con los cortes de pantalla o las áreas de gestos del sistema (por ejemplo, combinandoWindowInsets.displayCutoutconWindowInsets.systemGesturesen los controles inferiores para que la barra deslizante de búsqueda no entre en conflicto con los gestos de deslizamiento en el borde). - Oculta las barras del sistema con
WindowInsetsControllerCompatdentro de unDisposableEffect, lo que garantiza que se restablezca la visibilidad de la IU del sistema cuando se salga del elemento componible.
@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) ), ) }, ) }
Calcula el tamaño dinámico de la ventana y las actualizaciones de diseño
Calcular el ancho o la altura de la pantalla solo una vez al inicio de la app hace que los diseños dependan de valores inactivos cuando cambia la configuración del dispositivo, como cuando se despliega un dispositivo plegable, se cambia el tamaño de una sesión multiventana o se rota la pantalla.
En estos casos, incluso si un componente secundario usa correctamente
Modifier.fillMaxWidth(), no se adaptará si su contenedor superior
está restringido por dimensiones obsoletas, lo que provoca estiramientos, recortes o
diseños que no responden.
En el siguiente ejemplo, el fotograma de la izquierda ilustra la renderización correcta en un viewport estándar, mientras que el fotograma de la derecha muestra la falla de las dimensiones de la ventana obsoletas para adaptarse cuando se despliega un dispositivo, lo que genera un diseño de contenido que no responde.
Para evitar restricciones de diseño obsoletas, usa la API de consulta de medios de Jetpack. Como esta API es experimental y está inhabilitada de forma predeterminada,
primero habilita la función mediaQuery configurando
ComposeUiFlags.isMediaQueryIntegrationEnabled = true (por ejemplo, antes
de llamar a setContent) y habilita la opción con
@OptIn(ExperimentalMediaQueryApi::class).
Usa derivedMediaQuery para evaluar las condiciones del tamaño de la ventana actual, como windowWidth, de modo que el diseño se actualice cuando cambie la ventana sin recomposiciones innecesarias. Puedes combinar
derivedMediaQuery con puntos de interrupción WindowSizeClass para
cambiar entre diseños de reproductor de un solo panel y de varios paneles a medida que se expande la ventana:
@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 el escalamiento de contenido y las relaciones de aspecto
Distingue entre administrar el área de contenedor disponible y escalar el contenido multimedia en sí. Usa la administración de inserciones, como el padding del área segura, para establecer los límites del contenedor en relación con las barras del sistema y los cortes de pantalla. Luego, aplica estrategias de escalamiento dentro de esos límites. Para obtener orientación sobre el diseño de la estructuración de contenedores y el escalamiento de contenido visual en diferentes relaciones de aspecto, consulta Composición y estructura del contenido.
En el siguiente ejemplo, la imagen de la izquierda muestra cómo una estrategia de recorte puede cortar el contenido cuando se requiere visibilidad completa, mientras que la imagen de la derecha muestra cómo una estrategia de ajuste conserva la relación de aspecto nativa para la renderización de fotograma completo.
Los componentes de Media3 controlan automáticamente las relaciones de aspecto de video estándar, pero las configuraciones explícitas de ContentScale se vuelven fundamentales cuando se trabaja con diseños personalizados de Compose o contenedores restringidos (como feeds de redes sociales desplazables). Seleccionar una escala de contenido incorrecta puede provocar problemas de diseño, como distorsión de video (estiramiento) o formato letterbox no deseado que deja espacio vacío en el viewport. Administrar las plataformas de video de forma manual sin estas opciones también puede provocar que se rompan los diseños durante las rotaciones de pantalla o los cambios de estado de los dispositivos plegables.
Ya sea que se muestre un video de 16:9 en una pantalla de 4:3 o un video de 4:3 en una pantalla de 16:9, el elemento componible Player se establece de forma predeterminada en ContentScale.Fit. Esto mantiene visible todo el video sin recortarlo, ya que aplica formato de pantalla panorámica o formato de pantalla vertical.
Los cambios posteriores en el modo de visualización (como el zoom o el recorte) deben ser controlados por el usuario. Por ejemplo, cambia a ContentScale.Crop para
llenar el contenedor por completo. Un botón de activación de escalamiento interactivo equilibra los requisitos de diseño con la selección del usuario.
Ejemplos de implementaciones
Puedes aplicar la visibilidad de fotograma completo y controlar las relaciones de aspecto con las propiedades estándar de ContentScale de Compose.
Usa el elemento Player componible
El enfoque más sencillo y directo es usar el elemento de componibilidad Player. Como un wrapper de alto nivel que controla automáticamente los límites de escalamiento, vincula un ContentFrame para la renderización de video con superposiciones de control personalizables (topControls, centerControls, bottomControls) y una capa de obturador:
@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 ) }
Cuando crees un diseño de reproductor de video personalizado o coloques capas de IU personalizadas directamente sobre la transmisión de video, puedes usar ContentFrame directamente para obtener un control de diseño preciso y de nivel inferior.
Activar o desactivar el escalamiento dinámico controlado por el usuario
Para mejorar la experiencia de visualización de tu app, puedes agregar un botón de activación opcional que permita cambiar entre diferentes opciones de escalamiento de contenido. Si detectas un gesto de doble presión, puedes alternar de forma instantánea el estado del reproductor entre ContentScale.Fit y ContentScale.Crop. También puedes extender esta funcionalidad para admitir ajustes dinámicos de ContentScale con gestos de pellizcar para hacer zoom o de varios toques, de manera similar a las aplicaciones modernas de transmisión de 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, ) }
Si bien hay varias opciones de escalamiento de contenido, elige la opción de escalamiento según tu caso de uso: usa ContentScale.Crop para videos de formato corto o feeds desplazables en los que el objetivo principal sea llenar la pantalla, y usa ContentScale.Fit de forma predeterminada para contenido multimedia con información de margen vital, como resultados deportivos o subtítulos, para proteger el contexto visual esencial.