Menyiapkan inset jendela

Untuk mengizinkan aplikasi Anda memiliki kontrol penuh atas tempat aplikasi menggambar konten, ikuti langkah-langkah penyiapan berikut. Tanpa langkah-langkah ini, aplikasi Anda dapat menggambar warna hitam atau solid di belakang UI sistem, atau tidak beranimasi secara sinkron dengan keyboard software.

1. Targetkan Android 15 (level API 35) atau yang lebih tinggi untuk menerapkan tampilan layar penuh di Android 15 dan yang lebih tinggi. Aplikasi Anda ditampilkan di belakang UI sistem. Anda dapat menyesuaikan UI aplikasi dengan menangani inset.
2. Secara opsional, panggil enableEdgeToEdge() di Activity.onCreate(), yang memungkinkan aplikasi Anda ditampilkan dalam layar penuh di Android versi sebelumnya.

3. Tetapkan android:windowSoftInputMode="adjustResize" di entri AndroidManifest.xml Aktivitas Anda. Setelan ini memungkinkan aplikasi Anda menerima ukuran IME software sebagai inset, yang membantu Anda menerapkan tata letak dan padding yang sesuai saat IME muncul dan menghilang di aplikasi Anda.

   <!-- In your AndroidManifest.xml file: -->
   <activity
     android:name=".ui.MainActivity"
     android:label="@string/app_name"
     android:windowSoftInputMode="adjustResize"
     android:theme="@style/Theme.MyApplication"
     android:exported="true">
   

Menggunakan Compose API

Setelah Aktivitas Anda mengambil alih penanganan semua inset, Anda dapat menggunakan API Compose untuk memastikan konten tidak tertutup dan elemen yang dapat berinteraksi tidak tumpang-tindih dengan UI sistem. API ini juga menyinkronkan tata letak aplikasi Anda dengan perubahan inset.

Misalnya, ini adalah metode paling dasar untuk menerapkan inset ke konten seluruh aplikasi Anda:

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

    enableEdgeToEdge()

    setContent {
        Box(Modifier.safeDrawingPadding()) {
            // the rest of the app
        }
    }
}
InsetsSnippets.kt

Cuplikan ini menerapkan inset jendela safeDrawing sebagai padding di sekitar seluruh konten aplikasi. Meskipun ini memastikan bahwa elemen yang dapat berinteraksi tidak tumpang-tindih dengan UI sistem, ini juga berarti bahwa tidak ada aplikasi yang akan digambar di belakang UI sistem untuk mencapai efek layar penuh. Untuk memanfaatkan seluruh jendela sepenuhnya, Anda perlu menyetel secara cermat tempat inset diterapkan berdasarkan layar per layar atau komponen per komponen.

Semua jenis inset ini dianimasikan secara otomatis dengan animasi IME yang di-backport ke API 21. Dengan demikian, semua tata letak Anda yang menggunakan inset ini juga dianimasikan secara otomatis saat nilai inset berubah.

Ada dua cara utama untuk menggunakan jenis inset ini guna menyesuaikan tata letak Composable Anda: pengubah padding dan pengubah ukuran inset.

Pengubah padding

Modifier.windowInsetsPadding(windowInsets: WindowInsets) menerapkan inset jendela yang diberikan sebagai padding, dan berfungsi seperti Modifier.padding. Misalnya, Modifier.windowInsetsPadding(WindowInsets.safeDrawing) menerapkan inset gambar yang aman sebagai padding di keempat sisi.

Ada juga beberapa metode utilitas bawaan untuk jenis inset yang paling umum. Modifier.safeDrawingPadding() adalah salah satu metode tersebut, yang setara dengan Modifier.windowInsetsPadding(WindowInsets.safeDrawing). Ada pengubah analog untuk jenis inset lainnya.

Pengubah ukuran inset

Pengubah berikut menerapkan jumlah inset jendela dengan menyetel ukuran komponen menjadi ukuran inset:

Pengubah ini sangat berguna untuk menentukan ukuran Spacer yang menempati ruang inset:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

Konsumsi inset

Pengubah padding inset (windowInsetsPadding dan helper seperti safeDrawingPadding) secara otomatis menggunakan bagian inset yang diterapkan sebagai padding. Saat mempelajari lebih dalam hierarki komposisi, pengubah padding inset bertingkat dan pengubah ukuran inset mengetahui bahwa sebagian inset telah digunakan oleh pengubah padding inset luar, dan menghindari penggunaan bagian inset yang sama lebih dari sekali yang akan menghasilkan terlalu banyak ruang tambahan.

Pengubah ukuran inset juga menghindari penggunaan bagian inset yang sama lebih dari sekali jika inset telah digunakan. Namun, karena mengubah ukuran secara langsung, inset tersebut tidak menggunakan inset itu sendiri.

Akibatnya, menyarangkan pengubah padding akan otomatis mengubah jumlah padding yang diterapkan ke setiap composable.

Dengan melihat contoh LazyColumn yang sama seperti sebelumnya, LazyColumn diubah ukurannya oleh pengubah imePadding. Di dalam LazyColumn, item terakhir diberi ukuran agar memiliki tinggi bagian bawah kolom sistem:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

Saat IME ditutup, pengubah imePadding() tidak menerapkan padding, karena IME tidak memiliki tinggi. Karena pengubah imePadding() tidak menerapkan padding, tidak ada inset yang digunakan, dan tinggi Spacer akan menjadi ukuran sisi bawah kolom sistem.

Saat IME terbuka, inset IME akan dianimasikan agar sesuai dengan ukuran IME, dan pengubah imePadding() mulai menerapkan padding bawah untuk mengubah ukuran LazyColumn saat IME terbuka. Saat pengubah imePadding() mulai menerapkan padding bawah, pengubah ini juga mulai menggunakan jumlah inset tersebut. Oleh karena itu, tinggi Spacer mulai berkurang, karena bagian jarak untuk kolom sistem telah diterapkan oleh pengubah imePadding(). Setelah pengubah imePadding() menerapkan jumlah padding bawah yang lebih besar daripada kolom sistem, tinggi Spacer adalah nol.

Saat IME ditutup, perubahan terjadi secara terbalik: Spacer mulai meluas dari tinggi nol setelah imePadding() menerapkan kurang dari sisi bawah kolom sistem, hingga akhirnya Spacer cocok dengan tinggi sisi bawah kolom sistem setelah IME sepenuhnya dianimasikan.

Perilaku ini dilakukan melalui komunikasi antara semua pengubah windowInsetsPadding, dan dapat dipengaruhi dengan beberapa cara lain.

Modifier.consumeWindowInsets(insets: WindowInsets) juga menggunakan inset dengan cara yang sama seperti Modifier.windowInsetsPadding, tetapi tidak menerapkan inset yang digunakan sebagai padding. Hal ini berguna jika dikombinasikan dengan pengubah ukuran inset, untuk menunjukkan kepada elemen turunan bahwa sejumlah inset telah digunakan:

Column(Modifier.verticalScroll(rememberScrollState())) {
    Spacer(Modifier.windowInsetsTopHeight(WindowInsets.systemBars))

    Column(
        Modifier.consumeWindowInsets(
            WindowInsets.systemBars.only(WindowInsetsSides.Vertical)
        )
    ) {
        // content
        Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
    }

    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.systemBars))
}
InsetsSnippets.kt

Modifier.consumeWindowInsets(paddingValues: PaddingValues) berperilaku sangat mirip dengan versi dengan argumen WindowInsets, tetapi menggunakan PaddingValues arbitrer untuk digunakan. Hal ini berguna untuk memberi tahu turunan saat padding atau penspasian disediakan oleh mekanisme lain selain pengubah padding inset, seperti Modifier.padding biasa atau pengatur jarak tinggi tetap:

Column(Modifier.padding(16.dp).consumeWindowInsets(PaddingValues(16.dp))) {
    // content
    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
}
InsetsSnippets.kt

Jika inset jendela mentah diperlukan tanpa penggunaan, gunakan nilai WindowInsets secara langsung, atau gunakan WindowInsets.asPaddingValues() untuk menampilkan PaddingValues inset yang tidak terpengaruh oleh penggunaan. Namun, karena peringatan berikut, sebaiknya gunakan pengubah padding inset jendela dan pengubah ukuran inset jendela jika memungkinkan.

Inset dan fase Jetpack Compose

Compose menggunakan API inti AndroidX yang mendasarinya untuk memperbarui dan menganimasikan inset, yang menggunakan API platform yang mendasarinya untuk mengelola inset. Karena perilaku platform tersebut, inset memiliki hubungan khusus dengan fase Jetpack Compose.

Nilai inset diperbarui setelah fase komposisi, tetapi sebelum fase tata letak. Artinya, membaca nilai inset dalam komposisi biasanya menggunakan nilai inset yang terlambat satu frame. Pengubah bawaan yang dijelaskan di halaman ini dibuat untuk menunda penggunaan nilai inset hingga fase tata letak, yang memastikan bahwa nilai inset digunakan pada frame yang sama saat diperbarui.