Android поддерживает различные форм-факторы, помимо обычных смартфонов с вертикальной ориентацией экрана, включая складные устройства, планшеты, многооконные режимы и внешние дисплеи. Если вы предполагаете, что геометрия экрана статична, медиаконтент может оказаться растянутым, обрезанным или непреднамеренно помещенным в леттербокс. Приложение должно динамически адаптироваться к различным соотношениям сторон исходных медиафайлов (от классического 4:3 до ультраширокого) в разных режимах отображения.
Большинство сбоев макета мультимедиа в Jetpack Compose связано с тремя распространенными архитектурными ошибками:
- Несогласованная обработка вставок окон и конфликты при отображении во весь экран.
- Несогласованное обновление макета из-за неправильного расчета размера окна.
- Неправильная настройка параметров масштабирования контента.
В этом руководстве рассматриваются стратегии и рекомендации по решению каждой из этих проблем. области с использованием Media3 и Jetpack Compose.
Как обрабатывать вставки окон и конфликты при отображении от края до края
На устройствах с Android 15 (уровень API 35) и более поздними версиями приложения, поддерживающие уровень API 35 или выше, по умолчанию отображаются от края до края. Системные строки, такие как строка состояния, панель навигации и строка заголовка рабочего стола, отображаются поверх контента приложения, а вырезы на экране могут скрывать его части.
Без надлежащего управления вставками окон возникают два основных конфликта макета:
- Перекрытие системной строки. Кадры видео, субтитры и элементы управления воспроизведением частично скрыты строкой состояния (часы, значки батареи), панелью навигации или вырезами на экране (вырезы для камеры). Общие инструкции по настройке приведены в статье Как настроить показ рекламы на весь экран.
- Перекрытие строки заголовка в режиме компьютера. В многооконном режиме система добавляет верхнюю строку заголовка для управления окнами. Если в стандартных макетах, которые отображают персонализированные заголовки или медиахолсты без полей, не учитывать эту панель, то кадры видео и верхние элементы управления воспроизведением будут скрыты и недоступны для нажатия. Подробнее о поддержке многооконного режима…
Стратегии управления вставками
Ваше приложение должно динамически адаптироваться к системным отступам в зависимости от того, находится ли проигрыватель в неиммерсивном режиме или режиме погружения.
Конфигурации без иммерсивного режима
При обычном воспроизведении системные строки остаются видимыми, чтобы сохранить контекст устройства.
Если проигрыватель растянут до краев окна, примените windowInsetsPadding с WindowInsets.safeDrawing и only к каждой панели управления PlayerDefaults на краях, где она соприкасается с системными строками или вырезом на экране (например, Top + Horizontal на TopControls и Bottom + Horizontal на BottomControls). Это позволит не перекрывать элементы управления системными строками, пока видео растянуто по всему контейнеру.
@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 ) ), ) }, ) }
Конфигурации с эффектом присутствия (вертикальная и горизонтальная ориентация)
В полноэкранном режиме погружения цель состоит в том, чтобы максимально увеличить холст для кинематографического опыта, сохраняя при этом доступность элементов управления воспроизведением:
- Примените
windowInsetsPaddingк оверлеям элементов управления мультимедиа (например, верхним и нижним элементам управления), чтобы они не перекрывали вырезы на экране или области системных жестов. Например, можно объединитьWindowInsets.displayCutoutсWindowInsets.systemGesturesна нижних элементах управления, чтобы панель перемотки не мешала жестам пролистывания от края экрана. - Скройте системные строки с помощью
WindowInsetsControllerCompatвнутриDisposableEffect. Убедитесь, что видимость системного интерфейса восстанавливается при выходе из 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) ), ) }, ) }
Рассчитывать динамический размер окна и обновлять макет
Если ширина или высота экрана рассчитывается только один раз при запуске приложения, макеты будут использовать устаревшие значения при изменении конфигурации устройства, например когда складное устройство раскладывается, размер сеанса в многооконном режиме изменяется или дисплей поворачивается.
В таких случаях, даже если дочерний компонент правильно использует Modifier.fillMaxWidth(), он не сможет адаптироваться, если его родительский контейнер ограничен устаревшими размерами, что приведет к растяжению, обрезке или неадаптивным макетам.
В следующем примере левый фрейм иллюстрирует правильный рендеринг в стандартном окне просмотра, а правый фрейм демонстрирует, что устаревшие размеры окна не адаптируются при раскладывании устройства, что приводит к неотзывчивому макету контента.
Чтобы избежать устаревших ограничений макета, используйте Jetpack Media Query API. Поскольку этот API является экспериментальным и по умолчанию отключен, сначала включите функцию mediaQuery, задав ComposeUiFlags.isMediaQueryIntegrationEnabled = true (например, перед вызовом setContent), и включите его с помощью @OptIn(ExperimentalMediaQueryApi::class).
Используйте derivedMediaQuery, чтобы оценивать условия для текущего размера окна, например windowWidth. Это позволит обновлять макет при изменении окна без лишних рекомпозиций. Вы можете комбинировать контрольные точки derivedMediaQuery с WindowSizeClass, чтобы переключаться между макетами проигрывателя с одной и несколькими панелями при расширении окна:
@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() } } } }
Как настроить масштабирование контента и соотношение сторон
Различайте управление доступной областью контейнера и масштабирование самого медиаконтента. Используйте управление вставками, например полями безопасной зоны, чтобы задать границы контейнера относительно системных строк и вырезов на экране. Затем примените стратегии масштабирования в этих границах. Рекомендации по структурированию контейнеров и масштабированию визуального контента для разных соотношений сторон приведены в разделе Композиция и структура контента.
На изображении слева показано, как при кадрировании может быть обрезана часть контента, а на изображении справа – как при подгонке сохраняется исходное соотношение сторон для полнокадрового рендеринга.
Компоненты Media3 автоматически обрабатывают стандартные соотношения сторон видео, но явные конфигурации ContentScale становятся критически важными при работе с пользовательскими макетами Compose или ограниченными контейнерами (например, прокручиваемыми лентами социальных сетей). Если выбрать неподходящий масштаб, могут возникнуть проблемы с макетом, например искажение (растягивание) видео или нежелательное кашетирование, при котором в области просмотра остается пустое пространство. Если вы будете управлять видеоповерхностями вручную без этих параметров, то при повороте экрана или изменении состояния складного устройства макеты могут отображаться некорректно.
При показе видео с соотношением сторон 16:9 на экране 4:3 или видео 4:3 на экране 16:9 composable-функция Player по умолчанию использует ContentScale.Fit. Это позволяет показывать видео полностью, без обрезки, за счет добавления черных полос сверху и снизу или по бокам.
Последующие изменения режима отображения (например, масштабирование или кадрирование) должны выполняться пользователем. Например, переключитесь на ContentScale.Crop, чтобы полностью заполнить контейнер. Интерактивный переключатель масштабирования позволяет найти баланс между требованиями к макету и выбором пользователя.
Примеры кода
Вы можете принудительно включить видимость полного кадра и управлять соотношением сторон с помощью стандартных свойств Compose ContentScale.
Используйте composable-функцию Player
Самый простой и прямой подход – использовать composable-функцию Player. Он служит высокоуровневой оболочкой, которая автоматически обрабатывает границы масштабирования, и объединяет ContentFrame для отрисовки видео с настраиваемыми оверлеями управления (topControls, centerControls, bottomControls) и слоем затвора:
@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 ) }
При создании собственного макета видеопроигрывателя или размещении собственных слоев интерфейса непосредственно над видеопотоком вы можете использовать ContentFrame напрямую для точного управления макетом на более низком уровне.
Переключатель динамического масштабирования, управляемого пользователем
Чтобы улучшить качество просмотра вашего приложения, вы можете добавить дополнительный переключатель для переключения между различными вариантами масштабирования контента. Распознавая двойное нажатие, вы можете мгновенно переключать состояние проигрывателя между ContentScale.Fit и ContentScale.Crop. Вы также можете расширить эту функциональность, чтобы поддерживать динамическую настройку ContentScale с помощью жестов масштабирования или других жестов с несколькими касаниями, аналогично современным приложениям для потоковой передачи видео.
@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, ) }
Хотя существует несколько вариантов масштабирования контента, выбирайте вариант в зависимости от вашего сценария использования: используйте ContentScale.Crop для коротких видео или прокручиваемых лент, где заполнение экрана является основной целью, и по умолчанию используйте ContentScale.Fit для медиафайлов с важной информацией на полях, например спортивными результатами или субтитрами, чтобы сохранить важный визуальный контекст.