Menskalakan konten media di berbagai faktor bentuk

Android mendukung beragam faktor bentuk selain smartphone potret konvensional, termasuk perangkat foldable, tablet, lingkungan mode jendela desktop, dan layar eksternal. Jika Anda mengasumsikan geometri layar bersifat statis, konten media dapat terpotong, terentang, atau memiliki tampilan lebar yang tidak diinginkan. Aplikasi Anda harus beradaptasi secara dinamis dengan berbagai rasio aspek media sumber (dari 4:3 klasik hingga ultra-lebar) di berbagai mode tampilan yang terus berkembang.

Sebagian besar kegagalan tata letak media di Jetpack Compose berasal dari tiga kesalahan umum arsitektur:

  • Penanganan inset jendela yang tidak konsisten dan tumpang-tindih tampilan layar penuh.
  • Update tata letak yang tidak konsisten karena penghitungan ukuran jendela yang salah.
  • Kesalahan konfigurasi opsi penskalaan konten.

Panduan ini membahas strategi dan praktik terbaik untuk menangani setiap area ini menggunakan Media3 dan Jetpack Compose.

Menangani inset jendela dan konflik layar penuh

Pada perangkat yang menjalankan Android 15 (level API 35) dan yang lebih tinggi, aplikasi yang menargetkan level API 35 atau yang lebih tinggi ditampilkan dalam tampilan layar penuh secara default. Kolom sistem seperti status bar, menu navigasi, dan kolom teks desktop digambar di atas konten aplikasi Anda, dan potongan layar dapat mengaburkan bagian-bagiannya.

Tanpa pengelolaan inset jendela yang tepat, dua konflik tata letak utama akan terjadi:

  • Tumpang-tindih kolom sistem: Frame video, subtitel, dan kontrol pemutaran sebagian terhalang oleh status bar (jam, ikon baterai), gestur atau menu navigasi, atau potongan layar (notch kamera). Untuk panduan penyiapan umum, lihat Menyiapkan tampilan layar penuh.
  • Gangguan kolom teks mode desktop: Dalam mode jendela desktop, sistem memperkenalkan kolom teks atas untuk pengelolaan jendela. Tata letak standar yang merender header kustom atau kanvas media layar penuh tanpa memperhitungkan kolom teks ini akan menyebabkan frame video dan kontrol pemutaran atas tertutup dan tidak dapat diklik. Untuk mengetahui detail selengkapnya tentang status jendela, lihat Mendukung mode jendela desktop.
Status bar sistem tumpang-tindih dengan kanvas media layar penuh dan kontrol pemutaran. Menu navigasi gestur tumpang-tindih dengan kanvas media layar penuh. Panel teks desktop tumpang-tindih dengan kontrol pemutaran video di bagian atas.
Gambar 1. Status bar sistem, menu navigasi gestur, dan kolom teks desktop tumpang-tindih dengan kanvas media layar penuh serta mengaburkan konten video dan kontrol pemutaran.

Strategi pengelolaan inset

Aplikasi Anda harus beradaptasi secara dinamis dengan inset sistem berdasarkan apakah pemain berada dalam mode non-imersif atau imersif.

Konfigurasi non-imersif

Dalam pemutaran non-imersif, kolom sistem tetap terlihat untuk mempertahankan konteks perangkat.

Saat pemutar meluas ke tepi jendela, terapkan windowInsetsPadding dengan WindowInsets.safeDrawing dan only ke setiap kolom kontrol PlayerDefaults di tepi tempatnya bertemu dengan kolom sistem atau potongan layar (misalnya, Top + Horizontal di TopControls dan Bottom + Horizontal di BottomControls). Tindakan ini akan menjaga kontrol tetap bersih dari kolom sistem saat platform video meluas di seluruh penampung.

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

Dalam mode non-imersif, aplikasi mengintegrasikan padding inset jendela untuk menggeser konten ke dalam secara dinamis.
Gambar 2. Dalam mode non-imersif, aplikasi menerapkan padding inset jendela untuk menggeser kontrol ke dalam.

Konfigurasi imersif (potret dan lanskap)

Dalam mode imersif layar penuh, tujuannya adalah memaksimalkan kanvas untuk pengalaman sinematik sekaligus menjaga kontrol pemutaran tetap dapat diakses:

  1. Terapkan windowInsetsPadding ke overlay kontrol media (seperti kontrol atas dan bawah) untuk mencegahnya tumpang-tindih dengan potongan layar atau area gestur sistem (misalnya, menggabungkan WindowInsets.displayCutout dengan WindowInsets.systemGestures pada kontrol bawah sehingga bilah geser tidak bertentangan dengan gestur geser tepi).
  2. Sembunyikan kolom sistem menggunakan WindowInsetsControllerCompat di dalam DisposableEffect, untuk memastikan visibilitas UI sistem dipulihkan saat keluar dari 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)
            ),
      )
    },
  )
}

Kolom sistem otomatis disembunyikan saat pemutar video memasuki mode imersif, sehingga memberikan pengalaman sinematik layar penuh.
Gambar 3. Kolom sistem disembunyikan saat pemutar video memasuki mode imersif.

Menghitung ukuran jendela dinamis dan update tata letak

Menghitung lebar atau tinggi layar hanya sekali saat aplikasi dimulai akan menyebabkan tata letak mengandalkan nilai yang sudah tidak berlaku saat konfigurasi perangkat berubah—seperti saat perangkat foldable dibentangkan, sesi multi-aplikasi diubah ukurannya, atau layar diputar.

Dalam kasus ini, meskipun komponen turunan menggunakan Modifier.fillMaxWidth() dengan benar, komponen tersebut akan gagal beradaptasi jika penampung induknya dibatasi oleh dimensi yang sudah tidak berlaku, sehingga menyebabkan tata letak yang meregang, terpotong, atau tidak responsif.

Dalam contoh berikut, frame kiri mengilustrasikan rendering yang benar pada area pandang standar, sedangkan frame kanan menunjukkan kegagalan dimensi jendela yang tidak berlaku untuk beradaptasi saat perangkat dibentangkan, sehingga menghasilkan tata letak konten yang tidak responsif.

Rendering yang benar di area pandang standar dengan adaptasi rasio aspek dinamis. Kegagalan dimensi jendela yang tidak berlaku untuk beradaptasi saat perangkat dibentangkan.
Gambar 4. Perbandingan adaptasi rasio aspek dinamis.

Untuk menghindari batasan tata letak yang tidak berlaku, gunakan Jetpack kueri media API. Karena API ini bersifat eksperimental dan dinonaktifkan secara default, aktifkan fungsi mediaQuery terlebih dahulu dengan menetapkan ComposeUiFlags.isMediaQueryIntegrationEnabled = true (misalnya, sebelum memanggil setContent), dan ikut serta dengan @OptIn(ExperimentalMediaQueryApi::class).

Gunakan derivedMediaQuery untuk mengevaluasi kondisi pada ukuran jendela saat ini, seperti windowWidth, sehingga tata letak Anda diperbarui saat jendela berubah tanpa rekomposisi yang tidak perlu. Anda dapat menggabungkan derivedMediaQuery dengan titik henti sementara WindowSizeClass untuk beralih antara tata letak pemutar panel tunggal dan multi-panel saat jendela diperluas:

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

Mengonfigurasi penskalaan konten dan rasio aspek

Bedakan antara mengelola area penampung yang tersedia dan menskalakan konten media itu sendiri. Gunakan pengelolaan inset, seperti padding area aman, untuk menetapkan batas penampung yang relatif terhadap kolom sistem dan potongan layar. Kemudian, terapkan strategi penskalaan dalam batasan tersebut. Untuk panduan desain tentang cara menyusun penampung dan menskalakan konten visual di berbagai rasio aspek, lihat Komposisi dan struktur konten.

Dalam contoh berikut, gambar kiri menunjukkan bagaimana strategi pemangkasan dapat memotong konten saat visibilitas penuh diperlukan, sedangkan gambar kanan menunjukkan bagaimana strategi penyesuaian mempertahankan rasio aspek native untuk rendering frame penuh.

Strategi pemangkasan yang menyebabkan hilangnya konten secara signifikan saat visibilitas penuh diperlukan. Strategi penyesuaian yang mempertahankan rasio aspek native untuk rendering frame penuh.
Gambar 5. Perbandingan perilaku penskalaan.

Komponen Media3 menangani rasio aspek video standar secara otomatis, tetapi konfigurasi ContentScale eksplisit menjadi penting saat bekerja dengan tata letak Compose kustom atau penampung yang dibatasi (seperti feed media sosial yang dapat di-scroll). Memilih skala konten yang tidak tepat dapat menyebabkan masalah tata letak—seperti distorsi video (peregangan) atau letterbox yang tidak diinginkan yang menyisakan ruang kosong di area pandang. Mengelola platform video secara manual tanpa opsi ini juga dapat menyebabkan tata letak rusak selama rotasi layar atau perubahan status perangkat perangkat foldable.

Baik menampilkan video 16:9 di layar 4:3 atau video 4:3 di layar 16:9, composable Player ditetapkan secara default ke ContentScale.Fit. Hal ini membuat video lengkap tetap terlihat tanpa terpotong dengan menerapkan tampilan lebar atau tampilan pilar.

Perubahan mode tampilan berikutnya (seperti zoom atau pemangkasan) harus didorong oleh pengguna. Misalnya, beralihlah ke ContentScale.Crop untuk mengisi penampung sepenuhnya. Tombol penskalaan interaktif menyeimbangkan persyaratan tata letak dengan pilihan pengguna.

Contoh implementasi

Anda dapat menerapkan visibilitas frame penuh dan menangani rasio aspek menggunakan properti ContentScale Compose standar.

Menggunakan composable Player

Pendekatan paling sederhana dan langsung adalah menggunakan composable Player. Berfungsi sebagai wrapper tingkat tinggi yang otomatis menangani batas penskalaan, class ini menyambungkan ContentFrame untuk rendering video dengan overlay kontrol yang dapat disesuaikan (topControls, centerControls, bottomControls) dan lapisan shutter:

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

Saat membuat tata letak pemutar video kustom atau menempatkan lapisan UI kustom langsung di atas streaming video, Anda dapat menggunakan ContentFrame secara langsung untuk kontrol tata letak tingkat rendah yang akurat.

Tombol penskalaan dinamis yang dikontrol pengguna

Untuk meningkatkan pengalaman menonton aplikasi, Anda dapat menambahkan tombol opsional untuk beralih di antara berbagai opsi penskalaan konten. Dengan mendeteksi gestur ketuk dua kali, Anda dapat langsung mengalihkan status pemutar antara ContentScale.Fit dan ContentScale.Crop. Anda juga dapat memperluas fungsi ini untuk mendukung penyesuaian ContentScale dinamis menggunakan cubit untuk zoom atau gestur multi-kontrol lainnya, mirip dengan aplikasi streaming video modern.

Gambar 6. Beralih antara ContentScale.Fit dan 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,
  )
}

Meskipun ada beberapa opsi penskalaan konten, pilih opsi penskalaan berdasarkan kasus penggunaan Anda: gunakan ContentScale.Crop untuk video pendek atau feed yang dapat di-scroll dengan tujuan utama mengisi layar, dan gunakan ContentScale.Fit secara default untuk media dengan informasi margin penting, seperti skor olahraga atau subtitel, untuk melindungi konteks visual yang penting.