O Android oferece suporte a uma ampla variedade de formatos além dos smartphones convencionais em modo retrato, incluindo dobráveis, tablets, ambientes de modo janela para computador e telas externas. Se você presumir que a geometria da tela é estática, o conteúdo de mídia pode acabar esticado, cortado ou com letterbox não intencional. O app precisa se adaptar dinamicamente a várias proporções de mídia de origem (do clássico 4:3 ao ultra-wide) em diferentes modos de exibição.
A maioria das falhas de layout de mídia no Jetpack Compose se deve a três armadilhas arquitetônicas comuns:
- Tratamento inconsistente de inserções de janela e colisões de ponta a ponta.
- Atualizações de layout inconsistentes devido ao cálculo incorreto do tamanho da janela.
- Configuração incorreta das opções de escalonamento de conteúdo.
Este guia aborda estratégias e práticas recomendadas para lidar com cada uma dessas áreas usando o Media3 e o Jetpack Compose.
Processar encartes de janela e colisões de ponta a ponta
Em dispositivos com o Android 15 (nível 35 da API) e versões mais recentes, os apps que segmentam o nível 35 da API ou versões mais recentes são mostrados de ponta a ponta por padrão. As barras de sistema, como a barra de status, a barra de navegação e a barra de legenda da área de trabalho, são renderizadas sobre o conteúdo do app, e os cortes da tela podem ocultar partes dele.
Sem o gerenciamento adequado de inserções de janela, ocorrem dois conflitos de layout principais:
- Sobreposições da barra de sistema: frames de vídeo, legendas e controles de mídia são parcialmente ocultados pela barra de status (relógio, ícones de bateria), pela barra de gestos ou de navegação ou por cortes da tela (entalhes da câmera). Para orientações gerais de configuração, consulte Configurar de ponta a ponta.
- Interferência da barra de legenda do modo área de trabalho: no modo janela para computador, o sistema introduz uma barra de legenda na parte de cima para o gerenciamento de janelas. Os layouts padrão que renderizam cabeçalhos personalizados ou telas de mídia de ponta a ponta sem considerar essa barra de legenda acabam com frames de vídeo e controles de mídia superiores ocultos e não clicáveis. Para mais detalhes sobre os estados de janela, consulte Suporte ao modo janela para computador.
Estratégias de gerenciamento de encartes
O app precisa se adaptar dinamicamente às inserções do sistema com base no modo imersivo ou não imersivo do player.
Configurações não imersivas
Na reprodução não imersiva, as barras de sistema permanecem visíveis para preservar o contexto do dispositivo.
Quando o player se estender até as bordas da janela, aplique
windowInsetsPadding com
WindowInsets.safeDrawing e only a cada
barra de controle PlayerDefaults nas bordas em que ela se encontra com as
barras do sistema ou o corte da tela (por exemplo, Top + Horizontal em TopControls
e Bottom + Horizontal em BottomControls). Isso mantém os controles livres de
barras do sistema enquanto a superfície do vídeo se estende pelo contêiner.
@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 ) ), ) }, ) }
Configurações imersivas (retrato e paisagem)
No modo imersivo de tela cheia, o objetivo é maximizar a tela para uma experiência cinematográfica, mantendo os controles de mídia acessíveis:
- Aplique
windowInsetsPaddinga sobreposições de controle de mídia (como controles superiores e inferiores) para evitar que elas se sobreponham a cortes da tela ou áreas de gestos do sistema (por exemplo, combinandoWindowInsets.displayCutoutcomWindowInsets.systemGesturesnos controles inferiores para que a barra de busca não entre em conflito com gestos de deslizar na borda). - Oculte as barras de sistema usando
WindowInsetsControllerCompatdentro de umDisposableEffect, garantindo que a visibilidade da IU do sistema seja restaurada ao sair do elemento combinável.
@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) ), ) }, ) }
Calcular o dimensionamento dinâmico de janelas e as atualizações de layout
Calcular a largura ou a altura da tela apenas uma vez na inicialização do app faz com que os layouts dependam de valores desatualizados quando a configuração do dispositivo muda, como quando um dispositivo dobrável é desdobrado, uma sessão de várias janelas é redimensionada ou a tela é girada.
Nesses casos, mesmo que um componente filho use corretamente
Modifier.fillMaxWidth(), ele não vai se adaptar se o contêiner
pai for restrito por dimensões desatualizadas, causando alongamento, corte ou
layouts que não respondem.
No exemplo a seguir, o frame à esquerda ilustra a renderização correta em uma janela de visualização padrão, enquanto o frame à direita demonstra a falha de adaptação das dimensões desatualizadas da janela quando um dispositivo é aberto, resultando em um layout de conteúdo não responsivo.
Para evitar restrições de layout desatualizadas, use a API Jetpack Media Query. Como essa API é experimental e está desativada por padrão,
primeiro ative a função mediaQuery definindo
ComposeUiFlags.isMediaQueryIntegrationEnabled = true (por exemplo, antes de
chamar setContent) e ative-a com
@OptIn(ExperimentalMediaQueryApi::class).
Use derivedMediaQuery para avaliar as condições no
tamanho atual da janela, como windowWidth, para que o layout seja atualizado quando a
janela mudar sem recomposições desnecessárias. É possível combinar
derivedMediaQuery com pontos de interrupção WindowSizeClass para
alternar entre layouts de player de painel único e de vários painéis conforme a janela se expande:
@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() } } } }
Configurar o dimensionamento de conteúdo e as proporções
Diferenciar o gerenciamento da área de contêiner disponível do dimensionamento do conteúdo de mídia. Use o gerenciamento de margens, como o preenchimento de área segura, para definir os limites do contêiner em relação às barras de sistema e aos cortes da tela. Em seguida, aplique estratégias de escalonamento dentro desses limites. Para orientações de design sobre como estruturar contêineres e dimensionar conteúdo visual em proporções, consulte Composição e estrutura de conteúdo.
No exemplo a seguir, a imagem à esquerda mostra como uma estratégia de corte pode cortar o conteúdo quando a visibilidade total é necessária, enquanto a imagem à direita mostra como uma estratégia de ajuste preserva a proporção nativa para renderização em tela cheia.
Os componentes do Media3 processam proporções de vídeo padrão automaticamente, mas
as configurações explícitas de ContentScale se tornam essenciais ao
trabalhar com layouts personalizados do Compose ou contêineres restritos (como
feeds de redes sociais roláveis). Selecionar uma escala de conteúdo inadequada pode causar problemas de layout,
como distorção de vídeo (alongamento) ou letterboxing não intencional que
deixa espaço vazio na janela de visualização. Gerenciar superfícies de vídeo manualmente sem
essas opções também pode resultar em layouts corrompidos durante rotações de tela ou
mudanças de estado de dispositivos dobráveis.
Seja ao mostrar um vídeo de 16:9 em uma tela de 4:3 ou um vídeo de 4:3 em uma tela de 16:9, o elemento combinável Player usa como padrão
ContentScale.Fit. Isso mantém o vídeo inteiro visível
sem cortes, aplicando letterbox ou pillarbox.
As mudanças subsequentes no modo de exibição (como zoom ou corte) precisam ser
orientadas pelo usuário. Por exemplo, mude para ContentScale.Crop para
preencher o contêiner completamente. Um botão interativo de dimensionamento equilibra os requisitos de layout
com a escolha do usuário.
Implementações de exemplo
É possível aplicar a visibilidade de frame completo e processar proporções usando as propriedades padrão
ContentScale do Compose.
Usar o elemento combinável Player
A abordagem mais simples e direta é usar o elemento combinável
Player. Ele funciona como um wrapper de alto nível que processa automaticamente os limites de escalonamento, combinando um ContentFrame para renderização de vídeo com
sobreposições de controle personalizáveis (topControls, centerControls,
bottomControls) e uma camada 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 ) }
Ao criar um layout de player de vídeo personalizado ou colocar camadas de interface personalizadas diretamente
sobre o stream de vídeo, use ContentFrame diretamente para
um controle de layout preciso e de nível inferior.
Botão de escalonamento dinâmico controlado pelo usuário
Para melhorar a experiência de visualização do app, adicione um botão opcional para
alternar entre diferentes opções de escala de conteúdo. Ao detectar um gesto de toque duplo, você pode alternar instantaneamente o estado do player entre ContentScale.Fit
e ContentScale.Crop. Também é possível estender essa funcionalidade para oferecer suporte a
ajustes dinâmicos de ContentScale usando o gesto de pinça para aplicar zoom ou outros gestos
multitoque, semelhantes aos aplicativos modernos de streaming de vídeo.
@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, ) }
Embora existam várias opções de dimensionamento de conteúdo, escolha a opção com base
no seu caso de uso: use ContentScale.Crop para vídeos de curta duração
ou feeds roláveis em que o objetivo principal é preencher a tela e
use ContentScale.Fit como padrão para mídias com informações de margem
importantes, como placares esportivos ou legendas, para proteger o contexto visual
essencial.