Medya içeriklerini farklı form faktörlerine göre ölçeklendirme

Android, geleneksel dikey akıllı telefonların yanı sıra katlanabilir cihazlar, tabletler, pencereli görüntüleme ortamları ve harici ekranlar gibi çeşitli form faktörlerini destekler. Ekran geometrisinin statik olduğunu varsayarsanız medya içeriği uzatılabilir, kırpılabilir veya istemeden sinemaskop biçimine getirilebilir. Uygulamanız, gelişen ekran modlarında çeşitli kaynak medya en boy oranlarına (klasik 4:3'ten ultra genişe kadar) dinamik olarak uyum sağlamalıdır.

Jetpack Compose'daki çoğu medya düzeni hatası, üç yaygın mimari sorundan kaynaklanır:

  • Tutarsız pencere içi öğe işleme ve uçtan uca çakışmalar.
  • Pencere boyutu yanlış hesaplandığı için düzen güncellemeleri tutarsız oluyordu.
  • İçerik ölçeklendirme seçeneklerinin yanlış yapılandırılması.

Bu kılavuzda, Media3 ve Jetpack Compose kullanarak bu alanların her birini ele almaya yönelik stratejiler ve en iyi uygulamalar ele alınmaktadır.

Pencere iç kısımlarını ve uçtan uca çakışmaları yönetme

Android 15 (API düzeyi 35) ve sonraki sürümleri çalıştıran cihazlarda, API düzeyi 35 veya sonraki sürümleri hedefleyen uygulamalar varsayılan olarak uçtan uca görüntülenir. Durum çubuğu, gezinme çubuğu ve masaüstü başlık çubuğu gibi sistem çubukları, uygulamanızın içeriğinin üzerine çizilir ve ekran kesikleri, içeriğin bazı kısımlarını gizleyebilir.

Doğru pencere iç boşluğu yönetimi olmadan iki büyük düzen çakışması meydana gelir:

  • Sistem çubuğu çakışmaları: Video kareleri, altyazılar ve oynatma kontrolleri; durum çubuğu (saat, pil simgeleri), hareket veya gezinme çubuğu ya da ekran kesikleri (kamera çentikleri) tarafından kısmen engelleniyor. Genel kurulum talimatları için Uçtan uca kurulum başlıklı makaleyi inceleyin.
  • Masaüstü modu başlık çubuğu müdahalesi: Masaüstü pencereli görüntüleme modunda sistem, pencere yönetimi için üst başlık çubuğu ekler. Özel başlıkları veya uçtan uca medya tuvallerini bu altyazı çubuğunu hesaba katmadan oluşturan standart düzenlerde, video kareleri ve üst oynatma kontrolleri gizlenir ve tıklanamaz hale gelir. Pencere durumları hakkında daha fazla bilgi için Masaüstü pencereli görüntüleme desteği başlıklı makaleyi inceleyin.
Uçtan uca medya tuvali ve oynatma kontrolleriyle çakışan sistem durum çubuğu. Hareketle gezinme çubuğu, uçtan uca medya tuvaliyle çakışıyor. Masaüstü altyazı çubuğu, üstteki video oynatma kontrolleriyle çakışıyor.
Şekil 1. Sistem durum çubuğu, hareketle gezinme çubuğu ve masaüstü altyazı çubuğu, uçtan uca medya tuvaliyle çakışıyor ve video içeriği ile oynatma kontrollerini engelliyor.

Böcek yönetimi stratejileri

Uygulamanız, oyuncunun yoğun içerik modunda olup olmadığına bağlı olarak sistem eklerine dinamik olarak uyum sağlamalıdır.

Sürükleyici olmayan yapılandırmalar

Sürükleyici olmayan oynatmada, cihaz bağlamını korumak için sistem çubukları görünür kalır.

Oynatıcı pencere kenarlarına kadar uzandığında, sistem çubuklarıyla veya ekran kesmesiyle birleştiği kenarlardaki her bir PlayerDefaults kontrol çubuğuna WindowInsets.safeDrawing ve only ile windowInsetsPadding uygulayın (örneğin, TopControls üzerinde Top + Horizontal ve BottomControls üzerinde Bottom + Horizontal). Bu sayede, video yüzeyi kapsayıcı boyunca uzanırken kontroller sistem çubuklarından uzak tutulur.

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

Yoğun içerik modu dışındaki modlarda uygulama, içeriği dinamik olarak içe kaydırmak için pencere iç dolgusunu entegre eder.
Şekil 2. Yoğun içerik modu dışındaki modlarda uygulama, kontrolleri içeri kaydırmak için pencere iç dolgusu uygular.

Sürükleyici yapılandırmalar (dikey ve yatay)

Tam ekran yoğun içerik modunda amaç, oynatma kontrollerini erişilebilir tutarken sinematik bir deneyim için tuvali en üst düzeye çıkarmaktır:

  1. Medya kontrolü yer paylaşımlarının (ör. üst ve alt kontroller) ekran kesintileri veya sistem hareketi alanlarıyla çakışmasını önlemek için bunlara windowInsetsPadding uygulayın (ör. alt kontrollerde WindowInsets.displayCutout ile WindowInsets.systemGestures öğesini birleştirerek arama çubuğunun kenardan kaydırma hareketleriyle çakışmamasını sağlayın).
  2. DisposableEffect içinde WindowInsetsControllerCompat kullanarak sistem çubuklarını gizleyin. Böylece, composable'dan çıkarken sistem kullanıcı arayüzü görünürlüğü geri yüklenir.

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

Video oynatıcı yoğun içerik moduna girdiğinde sistem çubuğu otomatik olarak gizlenir ve tam ekran sinematik bir deneyim sunar.
Şekil 3. Video oynatıcı yoğun içerik moduna girdiğinde sistem çubukları gizlenir.

Dinamik pencere boyutlandırma ve düzen güncellemelerini hesaplama

Ekran genişliğinin veya yüksekliğinin yalnızca bir kez, uygulama başlatılırken hesaplanması, cihaz yapılandırması değiştiğinde (ör. katlanabilir bir cihaz açıldığında, çok pencereli bir oturum yeniden boyutlandırıldığında veya ekran döndürüldüğünde) düzenlerin eski değerlere dayanmasına neden olur.

Bu gibi durumlarda, alt bileşen Modifier.fillMaxWidth()'yi doğru şekilde kullansa bile üst kapsayıcısı eski boyutlarla kısıtlanmışsa uyum sağlayamaz. Bu da uzama, kırpma veya yanıt vermeyen düzenlere neden olur.

Aşağıdaki örnekte, sol karede standart bir görüntü alanında doğru oluşturma gösterilirken sağ karede, cihaz açıldığında eski pencere boyutlarının uyum sağlayamaması ve bunun sonucunda duyarlı olmayan içerik düzeni gösterilmektedir.

Dinamik en boy oranı uyarlamasıyla standart görüntü alanında doğru oluşturma. Cihaz açıldığında eski pencere boyutlarının uyum sağlayamaması.
Şekil 4. Dinamik en boy oranı uyarlamasının karşılaştırması.

Eski düzen kısıtlamalarını önlemek için Jetpack Media Query API'yi kullanın. Bu API deneysel olduğundan ve varsayılan olarak devre dışı bırakıldığından, önce ComposeUiFlags.isMediaQueryIntegrationEnabled = true ayarını yaparak mediaQuery işlevini etkinleştirin (örneğin, setContent işlevini çağırmadan önce) ve @OptIn(ExperimentalMediaQueryApi::class) ile etkinleştirin.

windowWidth gibi geçerli pencere boyutundaki koşulları değerlendirmek için derivedMediaQuery kullanın. Böylece, pencere değiştiğinde düzeniniz gereksiz yeniden oluşturma işlemleri olmadan güncellenir. Pencere genişledikçe tek bölmeli ve çok bölmeli oynatıcı düzenleri arasında geçiş yapmak için derivedMediaQuery ile WindowSizeClass kesme noktalarını birleştirebilirsiniz:

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

İçerik ölçeklendirmeyi ve en boy oranlarını yapılandırma

Mevcut kapsayıcı alanını yönetme ile medya içeriğini ölçeklendirme arasındaki farkı ayırt edin. Kapsayıcı sınırlarını sistem çubuklarına ve ekran kesiklerine göre ayarlamak için güvenli alan dolgusu gibi iç metin yönetimini kullanın. Ardından bu sınırlar dahilinde ölçeklendirme stratejileri uygulayın. Kapsayıcıları yapılandırma ve görsel içerikleri en boy oranlarına göre ölçeklendirme konusunda tasarım rehberliği için İçerik oluşturma ve yapısı başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, soldaki resimde kırpma stratejisinin tam görünürlük gerektiğinde içeriği nasıl kesebileceği, sağdaki resimde ise sığdırma stratejisinin tam kare oluşturma için yerel en boy oranını nasıl koruduğu gösterilmektedir.

Tam görünürlük gerektiğinde önemli içerik kaybına neden olan kırpma stratejisi. Tam kare oluşturma için yerel en boy oranını koruyan sığdırma stratejisi.
Şekil 5. Ölçeklendirme davranışlarının karşılaştırması.

Media3 bileşenleri, standart video en boy oranlarını otomatik olarak işler ancak özel Oluşturma düzenleri veya kısıtlı kapsayıcılarla (kaydırılabilir sosyal medya feed'leri gibi) çalışırken açık ContentScale yapılandırmaları kritik hale gelir. Uygun olmayan bir içerik ölçeği seçmek, videonun bozulması (esnemesi) veya görüntü alanında boşluk bırakan istenmeyen sinemaskop gibi düzen sorunlarına yol açabilir. Bu seçenekler olmadan video yüzeylerini manuel olarak yönetmek, ekran döndürme veya katlanabilir cihaz durumu değişiklikleri sırasında düzenlerin bozulmasına da neden olabilir.

Player composable'ı, 16:9 videoyu 4:3 ekranda veya 4:3 videoyu 16:9 ekranda gösterirken varsayılan olarak ContentScale.Fit değerini kullanır. Bu sayede, videonun tamamı kırpılmadan, sinemaskop veya dikey çerçeveleme uygulanarak gösterilir.

Görüntüleme modunda daha sonra yapılacak değişiklikler (yakınlaştırma veya kırpma gibi) kullanıcı tarafından yapılmalıdır. Örneğin, kapsayıcıyı tamamen doldurmak için ContentScale.Crop seçeneğine geçin. Etkileşimli ölçeklendirme düğmesi, düzen gereksinimlerini kullanıcı tercihiyle dengeler.

Örnek uygulamalar

Standart Compose ContentScale özelliklerini kullanarak tam kare görünürlüğünü zorunlu kılabilir ve en boy oranlarını yönetebilirsiniz.

Player composable'ını kullanma

En basit ve doğrudan yaklaşım, Player composable'ını kullanmaktır. Ölçeklendirme sınırlarını otomatik olarak işleyen üst düzey bir sarmalayıcı görevi görür. Video oluşturma için ContentFrame'yi özelleştirilebilir kontrol yer paylaşımları (topControls, centerControls, bottomControls) ve bir deklanşör katmanıyla eşler:

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

Özel bir video oynatıcı düzeni oluştururken veya özel kullanıcı arayüzü katmanlarını doğrudan video akışının üzerine yerleştirirken hassas, daha alt düzey düzen kontrolü için doğrudan ContentFrame kullanabilirsiniz.

Kullanıcı kontrollü dinamik ölçeklendirme açma/kapatma düğmesi

Uygulamanızın görüntüleme deneyimini iyileştirmek için farklı içerik ölçeklendirme seçenekleri arasında geçiş yapmanızı sağlayan isteğe bağlı bir açma/kapatma düğmesi ekleyebilirsiniz. İki kez dokunma hareketini algılayarak oynatıcının durumunu anında ContentScale.Fit ve ContentScale.Crop arasında değiştirebilirsiniz. Bu işlevi, modern video akışı uygulamalarına benzer şekilde, iki parmakla yakınlaştırma veya diğer çoklu dokunma hareketlerini kullanarak dinamik ContentScale ayarlamalarını destekleyecek şekilde de genişletebilirsiniz.

Şekil 6. ContentScale.Fit ve ContentScale.Crop arasında geçiş yapma

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

İçerik ölçeklendirme için çeşitli seçenekler olsa da kullanım alanınıza göre ölçeklendirme seçeneğini belirleyin: Ekranı doldurmanın birincil hedef olduğu kısa format video veya kaydırılabilir feed'ler için ContentScale.Crop kullanın ve önemli görsel bağlamı korumak için spor skorları veya altyazılar gibi önemli kenar boşluğu bilgileri içeren medya için varsayılan olarak ContentScale.Fit kullanın.