Mendukung potongan layar

Mencoba cara Compose

Jetpack Compose adalah toolkit UI yang direkomendasikan untuk Android. Pelajari cara menggunakan potongan layar di Compose.

Potongan layar di Compose →

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

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

Dokumen ini menjelaskan cara menerapkan dukungan untuk perangkat yang memiliki potongan layar, termasuk cara menangani area potongan—yakni, persegi panjang dari tepi ke tepi di permukaan tampilan yang berisi potongan.

Memilih cara aplikasi Anda menangani area potongan

Jika Anda tidak ingin konten Anda tumpang-tindih dengan area potongan, biasanya Anda cukup memastikan bahwa konten tidak tumpang-tindih dengan status bar dan menu navigasi. Jika merender konten ke area potongan, gunakan WindowInsetsCompat.getDisplayCutout() untuk mengambil objek DisplayCutout yang berisi inset aman dan kotak pembatas untuk setiap potongan. API ini memungkinkan Anda memeriksa apakah konten tumpang-tindih dengan potongan, sehingga Anda dapat mengubah posisinya, jika perlu.

Anda juga dapat menentukan apakah konten ditata di belakang area potongan. Atribut tata letak jendela layoutInDisplayCutoutMode mengontrol cara konten digambar di area potongan. Anda dapat menetapkan layoutInDisplayCutoutMode ke salah satu nilai berikut:

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: konten dirender di area potongan saat potongan layar berada di area kolom sistem. Jika tidak, jendela tidak akan tumpang-tindih dengan potongan layar; misalnya, konten dapat diberi letterbox saat ditampilkan dalam mode lanskap. Jika aplikasi Anda menargetkan SDK 35, hal ini ditafsirkan sebagai ALWAYS untuk jendela non-floating.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS: konten selalu diizinkan untuk diperluas ke area potongan. Jika aplikasi Anda menargetkan SDK 35 dan berjalan di perangkat Android 15, ini adalah satu-satunya mode yang diizinkan untuk jendela non-floating guna memastikan tampilan layar penuh.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: konten dirender di area potongan baik dalam mode potret maupun lanskap. Jangan gunakan untuk jendela mengambang. Jika aplikasi Anda menargetkan SDK 35, hal ini ditafsirkan sebagai ALWAYS untuk jendela non-floating.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: konten tidak dirender di area potongan. Jika aplikasi Anda menargetkan SDK 35, ini ditafsirkan sebagai ALWAYS untuk jendela non-floating.

Anda dapat menetapkan mode potongan secara terprogram atau dengan menetapkan gaya dalam aktivitas Anda. Contoh berikut menentukan gaya untuk menerapkan atribut LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES ke aktivitas.

<style name="ActivityTheme">
  <item name="android:windowLayoutInDisplayCutoutMode">
    shortEdges <!-- default, shortEdges, or never -->
  </item>
</style>

Bagian berikut menjelaskan berbagai mode potongan secara lebih mendetail.

Perilaku default

Jika aplikasi Anda menargetkan SDK 35 dan berjalan di perangkat Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS adalah perilaku default, dan LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT ditafsirkan sebagai LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS untuk jendela non-floating.

Jika tidak, LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT adalah defaultnya.

Merender konten di area potongan tepi pendek

Jika aplikasi Anda menargetkan SDK 35 dan berjalan di perangkat Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES ditafsirkan sebagai LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS untuk jendela non-floating.

Dengan LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, konten akan meluas ke area potongan di tepi pendek layar baik pada mode potret maupun lanskap, terlepas dari apakah kolom sistem tersembunyi atau terlihat. Saat menggunakan mode ini, pastikan tidak ada konten penting yang tumpang-tindih dengan area potongan.

Gambar berikut adalah contoh LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES untuk perangkat dalam mode potret:

Gambar berikut adalah contoh LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES untuk perangkat dalam orientasi lanskap:

Dalam mode ini, jendela meluas di bawah potongan di tepi pendek layar dalam mode potret dan lanskap, terlepas dari apakah jendela menyembunyikan kolom sistem.

Potongan di sudut dianggap berada di tepi pendek:

Tidak merender konten di area potongan layar

Jika aplikasi Anda menargetkan SDK 35 dan berjalan di perangkat Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER ditafsirkan sebagai LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS untuk jendela non-floating.

Dengan LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, jendela tidak diizinkan untuk tumpang-tindih dengan area potongan.

Berikut adalah contoh LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER dalam potret:

Berikut adalah contoh LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER dalam mode lanskap:

Praktik terbaik untuk dukungan potongan layar

Saat bekerja dengan potongan layar, pertimbangkan hal berikut:

• Perhatikan penempatan elemen penting UI. Jangan biarkan area potongan mengaburkan teks, kontrol, atau informasi penting lain apa pun.
• Jangan tempatkan atau perluas elemen interaktif apa pun yang memerlukan pengenalan sentuhan halus ke area potongan. Sensitivitas sentuhan mungkin lebih rendah di area potongan.

• Jika memungkinkan, gunakan WindowInsetsCompat untuk mengambil tinggi status bar dan menentukan padding yang sesuai untuk diterapkan ke konten Anda. Hindari hardcoding tinggi status bar, karena hal ini dapat menyebabkan konten tumpang-tindih atau terpotong.

  

• Gunakan View.getLocationInWindow() untuk menentukan seberapa banyak ruang jendela yang digunakan aplikasi Anda. Jangan berasumsi bahwa aplikasi menggunakan seluruh jendela, dan jangan gunakan View.getLocationOnScreen().

• Gunakan mode potongan always, shortEdges, atau never jika aplikasi Anda perlu bertransisi ke dan dari mode imersif. Perilaku potongan default dapat menyebabkan konten di aplikasi Anda dirender di area potongan saat kolom sistem ada, tetapi tidak saat dalam mode imersif. Hal ini menyebabkan konten bergerak naik dan turun selama transisi, seperti yang ditunjukkan dalam contoh berikut.

  

• Dalam mode imersif, berhati-hatilah saat menggunakan koordinat jendela vs koordinat layar, karena aplikasi Anda tidak menggunakan seluruh layar saat diberi letterbox. Karena adanya letterbox ini, koordinat dari asal layar tidak sama dengan koordinat dari asal jendela. Jika diperlukan, Anda dapat mengubah koordinat layar menjadi koordinat tampilan menggunakan getLocationOnScreen(). Gambar berikut menunjukkan perbedaan koordinat saat konten diberi letterbox:

  

• Saat menangani MotionEvent, gunakan MotionEvent.getX() dan MotionEvent.getY() untuk menghindari masalah koordinat serupa. Jangan gunakan MotionEvent.getRawX() atau MotionEvent.getRawY().

Menguji cara konten dirender

Uji semua layar dan pengalaman aplikasi Anda. Uji di perangkat dengan jenis potongan yang berbeda, jika memungkinkan. Jika perangkat yang memiliki potongan layar tidak tersedia, Anda dapat menyimulasikan konfigurasi potongan yang umum di perangkat apa pun atau di emulator yang menjalankan Android 9 atau yang lebih tinggi dengan melakukan langkah berikut:

1. Aktifkan Opsi developer.
2. Di layar Opsi developer, scroll ke bawah ke bagian Menggambar, lalu pilih Simulasikan tampilan dengan potongan layar.

3. Pilih jenis potongan.

   

Referensi lainnya

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT