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.
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 ) ), ) }, ) }
Konfigurasi imersif (potret dan lanskap)
Dalam mode imersif layar penuh, tujuannya adalah memaksimalkan kanvas untuk pengalaman sinematik sekaligus menjaga kontrol pemutaran tetap dapat diakses:
- Terapkan
windowInsetsPaddingke overlay kontrol media (seperti kontrol atas dan bawah) untuk mencegahnya tumpang-tindih dengan potongan layar atau area gestur sistem (misalnya, menggabungkanWindowInsets.displayCutoutdenganWindowInsets.systemGesturespada kontrol bawah sehingga bilah geser tidak bertentangan dengan gestur geser tepi). - Sembunyikan kolom sistem menggunakan
WindowInsetsControllerCompatdi dalamDisposableEffect, 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) ), ) }, ) }
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.
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.
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.
@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.