Cutout di Compose

Potongan layar adalah area di beberapa perangkat yang meluas ke permukaan layar. Potongan layar memungkinkan pengalaman dari tepi ke tepi sekaligus memberikan ruang untuk sensor penting di bagian depan perangkat.

Android mendukung potongan layar di perangkat yang menjalankan Android 9 (API level 28) dan lebih tinggi. Namun, produsen perangkat juga dapat mendukung potongan layar di perangkat yang menjalankan Android 8.1 atau yang lebih lama.

Halaman ini menjelaskan cara menerapkan dukungan untuk perangkat dengan potongan di Compose, termasuk cara menggunakan area potongan— yaitu, bagian tepi ke tepi persegi panjang di permukaan tampilan yang berisi potongan.

Kasus default

Secara default, potongan layar disertakan dalam informasi inset jendela. Karena itu, aplikasi Anda tidak akan menggambar di area potongan layar saat Anda mengikuti panduan untuk membuat aplikasi Anda ditampilkan di layar penuh.

Misalnya, ketika Anda menggunakan Modifier.windowInsetsPadding(WindowInsets.safeContent) atau Modifier.windowInsetsPadding(WindowInsets.safeDrawing), aplikasi Anda secara otomatis tidak akan menggambar di area tempat potongan ditempatkan. WindowInsets.safeContent dan WindowInsets.safeDrawing keduanya berisi informasi potongan layar dan tidak akan menggambar di tempat potongan perangkat alamat IP internalnya.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    WindowCompat.setDecorFitsSystemWindows(window, false)

    setContent {
        Box(Modifier.windowInsetsPadding(WindowInsets.safeContent)) {
            // Any composable inside here will avoid drawing behind cutouts
        }
    }
}
CutoutSnippets.kt

Untuk menyesuaikan perilaku ini lebih lanjut, Anda harus menangani informasi potongan sendiri.

Menangani informasi potongan secara manual

Anda dapat menangani potongan dengan salah satu cara berikut:

• Menggunakan WindowInsets.displayCutout

• Setelan dalam manifes tema dengan android:windowLayoutInDisplayCutoutMode

• Menetapkan opsi secara terprogram di Window dengan window.attributes.layoutInDisplayCutoutMode

• Mengakses objek Path potongan dengan LocalView.current.rootWindowInsets.displayCutout

Untuk Compose, sebaiknya tetapkan windowLayoutInDisplayCutoutMode ke default di tema keseluruhan Anda, lalu manfaatkan WindowInsets.displayCutout menangani inset dalam composable Anda:

Canvas(modifier = Modifier.fillMaxSize().windowInsetsPadding(WindowInsets.displayCutout)) {
    drawRect(Color.Red, style = Stroke(2.dp.toPx()))
}
CutoutSnippets.kt

Pendekatan ini memungkinkan Anda mematuhi padding displayCutout jika diperlukan, atau mengabaikannya jika tidak diperlukan.

Atau, Anda dapat menerapkan setelan yang sama dengan Cutout Tampilan dokumentasi yang dijelaskan dengan menetapkan baik tema aktivitas android:windowLayoutInDisplayCutoutMode ke tema lainnya opsi, atau menyetel atribut jendela menggunakan window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT. Namun, mode potongan akan diterapkan ke seluruh aktivitas, dan tidak dapat dikontrol per composable individual.

Untuk mengikuti pemangkasan tampilan di composable tertentu, tetapi tidak di composable lainnya, gunakan WindowInset.displayCutout. API ini memungkinkan Anda mengakses informasi potongan jika diperlukan.

Praktik terbaik

Saat menggunakan potongan layar, pertimbangkan hal berikut:

• Perhatikan penempatan elemen penting UI. Jangan biarkan area potongan mengaburkan teks, kontrol, atau informasi penting lainnya.
• Jangan tempatkan atau perluas elemen interaktif apa pun yang memerlukan sentuhan halus pengenalan ke area potongan. Sensitivitas sentuh mungkin lebih rendah di area potongan.
• Saat mengikuti panduan dari tepi ke tepi, informasi potongan disertakan dalam inset safeDrawing/safeContent.
• Jika memungkinkan, gunakan Modifier.windowInsetsPadding(WindowInsets.safeDrawing) untuk menentukan padding yang sesuai untuk diterapkan ke konten Anda. Hindari melakukan hardcode tinggi status bar, karena hal ini dapat menyebabkan tumpang-tindih atau terpotong saat ini.

Menguji cara konten dirender dengan potongan

Pastikan untuk menguji semua layar dan pengalaman aplikasi Anda. Uji pada perangkat dengan berbagai jenis potongan, jika memungkinkan. Jika Anda tidak memiliki perangkat dengan Anda dapat menyimulasikan konfigurasi potongan umum di perangkat atau emulator apa pun menjalankan Android 9 atau yang lebih baru dengan melakukan hal berikut:

1. Aktifkan Opsi developer.
2. Di layar Developer options, scroll ke bawah ke bagian Drawing dan pilih Simulate a display with a cutout.
3. Pilih jenis potongan.