Skalowanie treści multimedialnych na różnych formatach

Android obsługuje różne formaty urządzeń, nie tylko tradycyjne smartfony w orientacji pionowej, ale też urządzenia składane, tablety, tryb okien na pulpicie i wyświetlacze zewnętrzne. Jeśli założysz, że geometria ekranu jest statyczna, treści multimedialne mogą zostać rozciągnięte, przycięte lub nieumyślnie wyświetlone w formacie letterbox. Aplikacja musi dynamicznie dostosowywać się do różnych formatów obrazu multimediów źródłowych (od klasycznego 4:3 do ultraszerokiego) w różnych trybach wyświetlania.

Większość błędów układu multimediów w Jetpack Compose wynika z 3 typowych pułapek architektonicznych:

  • Niespójna obsługa wstawek okien i kolizje z trybem od krawędzi do krawędzi.
  • Niespójne aktualizacje układu z powodu nieprawidłowego obliczenia rozmiaru okna.
  • Nieprawidłowa konfiguracja opcji skalowania treści.

W tym przewodniku znajdziesz strategie i sprawdzone metody dotyczące każdego z tych obszarów przy użyciu Media3 i Jetpack Compose.

Obsługa kolizji między wstawkami okien i trybem od krawędzi do krawędzi

Na urządzeniach z Androidem 15 (API na poziomie 35) lub nowszym aplikacje kierowane na API na poziomie 35 lub wyższym są domyślnie wyświetlane bez ramki. Paski systemu, takie jak pasek stanu, pasek nawigacyjny i pasek podpisów na pulpicie, są wyświetlane nad treścią aplikacji, a wycięcia w ekranie mogą zasłaniać jej części.

Bez odpowiedniego zarządzania wstawkami okien występują 2 główne konflikty układu:

  • Nakładanie się pasków systemu: klatki wideo, napisy i elementy sterujące odtwarzaniem są częściowo zasłonięte przez pasek stanu (zegar, ikony baterii), pasek gestów lub pasek nawigacji albo wycięcia w ekranie (wycięcia na aparat). Ogólne wskazówki dotyczące konfiguracji znajdziesz w artykule Konfigurowanie wyświetlania od krawędzi do krawędzi.
  • Zakłócenia paska napisów w trybie pulpitu: w trybie okien na pulpicie system wprowadza górny pasek napisów do zarządzania oknami. W standardowych układach, które renderują niestandardowe nagłówki lub obszary multimedialne od krawędzi do krawędzi bez uwzględniania tego paska, klatki wideo i górne elementy sterujące odtwarzaniem są zasłonięte i nie można ich kliknąć. Więcej informacji o stanach okien znajdziesz w artykule Obsługa trybu okien na pulpicie.
Pasek stanu systemu nakładający się na obszar multimediów od krawędzi do krawędzi i elementy sterujące odtwarzaniem. Pasek nawigacji przy użyciu gestów nakłada się na obszar multimediów wyświetlany od krawędzi do krawędzi. Pasek napisów na komputerze nakłada się na górne elementy sterujące odtwarzaniem filmu.
Rysunek 1. Pasek stanu systemu, pasek nawigacji przy użyciu gestów i pasek podpisów na pulpicie nakładają się na obszar multimediów od krawędzi do krawędzi i zasłaniają treści wideo oraz elementy sterujące odtwarzaniem.

Strategie zarządzania wstawkami

Aplikacja powinna dynamicznie dostosowywać się do wstawek systemowych w zależności od tego, czy odtwarzacz jest w trybie imersji czy nie.

Konfiguracje niepełnoekranowe

W trybie odtwarzania bez pełnego ekranu paski systemowe pozostają widoczne, aby zachować kontekst urządzenia.

Gdy odtwarzacz rozciąga się do krawędzi okna, zastosuj windowInsetsPadding z WindowInsets.safeDrawing i only do każdego paska sterowania PlayerDefaults na krawędziach, gdzie styka się on z paskami systemowymi lub wycięciem w ekranie (np. Top + Horizontal na TopControls i Bottom + Horizontal na BottomControls). Dzięki temu elementy sterujące nie będą zasłaniać pasków systemowych, gdy powierzchnia filmu będzie rozciągać się na cały kontener.

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

W trybie innym niż imersyjny aplikacja integruje dopełnienie wstawki okna, aby dynamicznie przesuwać treści do wewnątrz.
Rysunek 2. W trybie innym niż imersyjny aplikacja stosuje dopełnienie wstawki okna, aby przesunąć elementy sterujące do wewnątrz.

Konfiguracje immersyjne (pionowa i pozioma)

W trybie imersji na pełnym ekranie celem jest maksymalne powiększenie obszaru roboczego, aby zapewnić wrażenia kinowe, przy jednoczesnym zachowaniu dostępu do elementów sterujących odtwarzaniem:

  1. Zastosuj windowInsetsPadding do nakładek opcji sterowania multimediami (takich jak górne i dolne elementy sterujące), aby zapobiec ich nakładaniu się na wycięcia w ekranie lub obszary gestów systemowych (np. połącz WindowInsets.displayCutout z WindowInsets.systemGestures w dolnych elementach sterujących, aby pasek przewijania nie kolidował z gestami przesuwania krawędzi).
  2. Ukryj paski systemu za pomocą WindowInsetsControllerCompat wewnątrz DisposableEffect, aby przywrócić widoczność interfejsu systemu po opuszczeniu funkcji kompozycyjnej.

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

Pasek systemowy automatycznie się ukrywa, gdy odtwarzacz wideo przechodzi w tryb imersji, co zapewnia wrażenia kinowe na pełnym ekranie.
Rysunek 3. Paski systemowe są ukrywane, gdy odtwarzacz wideo przechodzi w tryb imersji.

obliczanie dynamicznego rozmiaru okna i aktualizacji układu;

Obliczanie szerokości lub wysokości ekranu tylko raz podczas uruchamiania aplikacji powoduje, że układy opierają się na nieaktualnych wartościach, gdy zmienia się konfiguracja urządzenia – na przykład gdy urządzenie składane jest rozkładane, sesja w wielu oknach zmienia rozmiar lub wyświetlacz jest obracany.

W takich przypadkach, nawet jeśli komponent podrzędny prawidłowo używa Modifier.fillMaxWidth(), nie będzie mógł się dostosować, jeśli jego kontener nadrzędny jest ograniczony przez stałe wymiary, co spowoduje rozciąganie, przycinanie lub brak reakcji układów.

W przykładzie poniżej zrzut ekranu po lewej stronie pokazuje prawidłowe renderowanie w standardowym obszarze wyświetlania, a zrzut ekranu po prawej stronie pokazuje, że stałe wymiary okna nie dostosowują się do rozłożonego urządzenia, co powoduje, że układ treści nie jest elastyczny.

Prawidłowe renderowanie w standardowym widocznym obszarze z dynamicznym dostosowywaniem formatu obrazu. Nieaktualne wymiary okna nie dostosowują się po rozłożeniu urządzenia.
Rysunek 4. Porównanie dynamicznego dostosowywania formatu obrazu.

Aby uniknąć nieaktualnych ograniczeń układu, użyj interfejsu Jetpack Media Query API. Ten interfejs API jest eksperymentalny i domyślnie wyłączony, dlatego najpierw włącz funkcję mediaQuery, ustawiając ComposeUiFlags.isMediaQueryIntegrationEnabled = true (na przykład przed wywołaniem setContent), i wyraź zgodę za pomocą @OptIn(ExperimentalMediaQueryApi::class).

Użyj derivedMediaQuery, aby ocenić warunki dotyczące bieżącego rozmiaru okna, takie jak windowWidth, dzięki czemu układ będzie się aktualizować, gdy okno się zmieni, bez niepotrzebnych rekompozycji. Możesz połączyć derivedMediaQuery z punktami przerwania WindowSizeClass, aby przełączać się między układami odtwarzacza z jednym panelem i wieloma panelami w miarę powiększania okna:

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

Konfigurowanie skalowania treści i formatów obrazu

Rozróżniaj zarządzanie dostępnym obszarem kontenera i skalowanie samej treści multimedialnej. Używaj zarządzania wstawkami, np. dopełnienia bezpiecznego obszaru, aby ustawić granice kontenera względem pasków systemowych i wycięć w ekranie. Następnie zastosuj strategie skalowania w tych granicach. Wskazówki dotyczące projektowania i strukturyzowania kontenerów oraz skalowania treści wizualnych w różnych formatach obrazu znajdziesz w artykule Kompozycja i struktura treści.

W poniższym przykładzie obraz po lewej stronie pokazuje, jak strategia przycinania może odciąć zawartość, gdy wymagana jest pełna widoczność, a obraz po prawej stronie pokazuje, jak strategia dopasowywania zachowuje natywny format obrazu w celu renderowania pełnoklatkowego.

Strategia przycinania powoduje znaczną utratę treści, gdy wymagana jest pełna widoczność. Strategia dopasowania zachowująca natywny format obrazu na potrzeby renderowania pełnoklatkowego.
Rysunek 5. Porównanie zachowań skalowania.

Komponenty Media3 automatycznie obsługują standardowe formaty obrazu, ale jawne konfiguracje ContentScale stają się kluczowe, gdy pracujesz z niestandardowymi układami Compose lub ograniczonymi kontenerami (takimi jak przewijane strumienie w mediach społecznościowych). Wybór nieprawidłowej skali treści może prowadzić do problemów z układem, takich jak zniekształcenie (rozciągnięcie) filmu lub niezamierzony format letterbox, który pozostawia puste miejsce w widocznym obszarze. Ręczne zarządzanie powierzchniami wideo bez tych opcji może też powodować uszkodzenie układów podczas obracania ekranu lub zmiany stanu urządzenia składanego.

Niezależnie od tego, czy wyświetlasz film w formacie 16:9 na ekranie 4:3, czy film w formacie 4:3 na ekranie 16:9, element kompozycyjny Player domyślnie używa wartości ContentScale.Fit. Dzięki temu cały film jest widoczny bez przycinania, ponieważ stosowane są pasy u góry i u dołu lub po bokach.

Kolejne zmiany trybu wyświetlania (takie jak powiększanie lub przycinanie) powinny być inicjowane przez użytkownika. Możesz na przykład przełączyć na ContentScale.Crop, aby całkowicie wypełnić kontener. Interaktywny przełącznik skalowania równoważy wymagania dotyczące układu z wyborem użytkownika.

Przykładowe implementacje

Możesz wymusić widoczność pełnej klatki i obsługiwać formaty obrazu za pomocą standardowych właściwości ContentScale w Compose.

Używanie funkcji kompozycyjnej Player

Najprostszym i najbardziej bezpośrednim podejściem jest użycie funkcji kompozycyjnej Player. Działa jako kod otaczający wysokiego poziomu, który automatycznie obsługuje granice skalowania. Łączy on element ContentFrame do renderowania wideo z nakładkami sterującymi, które można dostosowywać (topControls, centerControls, bottomControls), oraz warstwą migawki:

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

Podczas tworzenia niestandardowego układu odtwarzacza wideo lub umieszczania niestandardowych warstw interfejsu bezpośrednio nad strumieniem wideo możesz używać bezpośrednio ContentFrame, aby uzyskać precyzyjną kontrolę nad układem na niższym poziomie.

Przełącznik dynamicznego skalowania kontrolowanego przez użytkownika

Aby poprawić komfort oglądania w aplikacji, możesz dodać opcjonalny przełącznik, który umożliwia przełączanie się między różnymi opcjami skalowania treści. Wykrywając gest dwukrotnego dotknięcia, możesz natychmiast przełączać stan odtwarzacza między ContentScale.Fit i ContentScale.Crop. Możesz też rozszerzyć tę funkcję, aby obsługiwała dynamiczne dostosowywanie ContentScale za pomocą gestu uszczypnięcia w celu powiększenia lub innych gestów wielodotykowych, podobnie jak w nowoczesnych aplikacjach do strumieniowego przesyłania filmów.

Rysunek 6. Przełączanie między ContentScale.Fit i 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,
  )
}

Dostępnych jest kilka opcji skalowania treści. Wybierz opcję skalowania na podstawie przypadku użycia: użyj ContentScale.Crop w przypadku krótkich filmów lub przewijanych kanałów, gdzie głównym celem jest wypełnienie ekranu, i domyślnie ContentScale.Fit w przypadku multimediów z ważnymi informacjami na marginesie, takimi jak wyniki sportowe lub napisy, aby chronić istotny kontekst wizualny.