Tentang inset jendela

Platform Android bertanggung jawab untuk menggambar UI sistem, seperti status bar dan menu navigasi. UI sistem ini ditampilkan, apa pun aplikasi yang digunakan pengguna.

WindowInsets memberikan informasi tentang UI sistem untuk memastikan aplikasi Anda menggambar di area yang benar dan UI Anda tidak tertutup oleh UI sistem.

Menampilkan tata letak layar penuh untuk menggambar di belakang kolom sistem
Gambar 1. Menggambar dari tepi ke tepi di belakang panel sistem.

Di Android 14 (API level 34) dan yang lebih lama, UI aplikasi Anda tidak digambar di bawah kolom sistem dan menampilkan potongan secara default.

Di Android 15 (API level 35) dan yang lebih tinggi, aplikasi Anda akan menggambar di bawah batang sistem dan menampilkan potongan setelah aplikasi menargetkan SDK 35. Hal ini menghasilkan pengalaman pengguna yang lebih lancar dan memungkinkan aplikasi Anda memanfaatkan sepenuhnya ruang jendela yang tersedia.

Menampilkan konten di belakang UI sistem disebut tampilan layar penuh. Di halaman ini, Anda akan mempelajari berbagai jenis inset, cara menggunakan inset dari tepi ke tepi, dan cara menggunakan API inset untuk menganimasikan UI dan memastikan konten aplikasi tidak terhalang oleh elemen UI sistem.

Dasar-dasar inset

Saat aplikasi menggunakan layar penuh, Anda harus memastikan bahwa konten dan interaksi penting tidak terhalang oleh UI sistem. Misalnya, jika tombol diletakkan di belakang menu navigasi, pengguna mungkin tidak dapat mengkliknya.

Ukuran UI sistem dan informasi tentang tempat penempatannya ditentukan melalui inset.

Setiap bagian UI sistem memiliki jenis inset yang sesuai yang menjelaskan ukuran dan tempat penempatannya. Misalnya, inset status bar memberikan ukuran dan posisi status bar, sedangkan inset menu navigasi memberikan ukuran dan posisi menu navigasi. Setiap jenis inset terdiri dari empat dimensi piksel: atas, kiri, kanan, dan bawah. Dimensi ini menentukan seberapa jauh UI sistem meluas dari sisi jendela aplikasi yang sesuai. Oleh karena itu, untuk menghindari tumpang-tindih dengan jenis UI sistem tersebut, UI aplikasi harus disisipkan dengan jumlah tersebut.

Jenis inset Android bawaan ini tersedia melalui WindowInsets:

WindowInsets.statusBars

Inset yang menjelaskan status bar. Ini adalah panel UI sistem atas yang berisi ikon notifikasi dan indikator lainnya.

WindowInsets.statusBarsIgnoringVisibility

Inset status bar saat terlihat. Jika status bar saat ini disembunyikan (karena memasuki mode layar penuh imersif), inset status bar utama akan kosong, tetapi inset ini tidak akan kosong.

WindowInsets.navigationBars

Inset yang menjelaskan menu navigasi. Ini adalah panel UI sistem di sisi kiri, kanan, atau bawah perangkat, yang menjelaskan taskbar atau ikon navigasi. Hal ini dapat berubah saat runtime berdasarkan metode navigasi pilihan pengguna dan berinteraksi dengan taskbar.

WindowInsets.navigationBarsIgnoringVisibility

Inset menu navigasi saat terlihat. Jika menu navigasi saat ini disembunyikan (karena memasuki mode layar penuh imersif), inset menu navigasi utama akan kosong, tetapi inset ini tidak akan kosong.

WindowInsets.captionBar

Inset yang menjelaskan dekorasi jendela UI sistem jika berada di jendela bentuk bebas, seperti kolom judul atas.

WindowInsets.captionBarIgnoringVisibility

Panel teks yang disisipkan saat terlihat. Jika panel teks saat ini disembunyikan, inset panel teks utama akan kosong, tetapi inset ini tidak akan kosong.

WindowInsets.systemBars

Gabungan inset panel sistem, yang mencakup status bar, menu navigasi, dan panel teks.

WindowInsets.systemBarsIgnoringVisibility

Inset panel sistem saat terlihat. Jika panel sistem saat ini disembunyikan (karena memasuki mode layar penuh imersif), inset panel sistem utama akan kosong, tetapi inset ini tidak akan kosong.

WindowInsets.ime

Inset yang menjelaskan jumlah ruang di bagian bawah yang ditempati keyboard software.

WindowInsets.imeAnimationSource

Inset yang menjelaskan jumlah ruang yang ditempati keyboard software sebelum animasi keyboard saat ini.

WindowInsets.imeAnimationTarget

Inset yang menjelaskan jumlah ruang yang akan ditempati keyboard virtual setelah animasi keyboard saat ini.

WindowInsets.tappableElement

Jenis inset yang menjelaskan informasi yang lebih mendetail tentang UI navigasi, yang memberikan jumlah ruang tempat "ketukan" akan ditangani oleh sistem, bukan aplikasi. Untuk menu navigasi transparan dengan navigasi gestur, beberapa elemen aplikasi dapat diketuk melalui UI navigasi sistem.

WindowInsets.tappableElementIgnoringVisibility

Inset elemen yang dapat diketuk saat terlihat. Jika elemen yang dapat diketuk saat ini disembunyikan (karena memasuki mode layar penuh imersif), inset elemen utama yang dapat diketuk akan kosong, tetapi inset ini tidak akan kosong.

WindowInsets.systemGestures

Inset yang mewakili jumlah inset tempat sistem akan menangkap gestur untuk navigasi. Aplikasi dapat menentukan secara manual penanganan gestur ini dalam jumlah terbatas melalui Modifier.systemGestureExclusion.

WindowInsets.mandatorySystemGestures

Subkumpulan gestur sistem yang akan selalu ditangani oleh sistem, dan yang tidak dapat dinonaktifkan melalui Modifier.systemGestureExclusion.

WindowInsets.displayCutout

Inset yang mewakili jumlah spasi yang diperlukan untuk menghindari tumpang-tindih dengan potongan layar (notch atau pinhole).

WindowInsets.waterfall

Inset yang mewakili area melengkung pada tampilan waterfall. Layar waterfall memiliki area melengkung di sepanjang tepi layar tempat layar mulai meliuk di sepanjang sisi perangkat.

Jenis ini diringkas oleh tiga jenis inset "aman" yang memastikan konten tidak terhalang:

Jenis inset "aman" ini melindungi konten dengan cara yang berbeda, berdasarkan inset platform yang mendasarinya:

  • Gunakan WindowInsets.safeDrawing untuk melindungi konten yang tidak boleh digambar di bawah UI sistem apa pun. Ini adalah penggunaan inset yang paling umum: untuk mencegah menggambar konten yang dikaburkan oleh UI sistem (sebagian atau sepenuhnya).
  • Gunakan WindowInsets.safeGestures untuk melindungi konten dengan gestur. Hal ini menghindari gestur sistem yang bertentangan dengan gestur aplikasi (seperti untuk sheet bawah, carousel, atau dalam game).
  • Gunakan WindowInsets.safeContent sebagai kombinasi WindowInsets.safeDrawing dan WindowInsets.safeGestures untuk memastikan konten tidak memiliki tumpang-tindih visual dan tidak ada tumpang-tindih gestur.
Berikutnya
Memastikan UI Anda berfungsi dengan inset jendela