Menambahkan dukungan untuk gestur kembali prediktif

Kembali Prediktif, fitur navigasi gestur, memungkinkan pengguna melihat pratinjau tujuan saat menggeser kembali.

Misalnya, menggunakan gestur kembali dapat menampilkan pratinjau animasi Layar utama di belakang aplikasi, seperti yang ditampilkan dalam mockup pada gambar 1.

Mulai Android 15, opsi developer untuk animasi kembali prediktif tidak lagi tersedia. Animasi sistem seperti kembali ke layar utama, lintas tugas, dan lintas aktivitas kini muncul untuk aplikasi yang telah mengaktifkan gestur kembali prediktif baik sepenuhnya atau di tingkat aktivitas.

Anda dapat menguji animasi kembali ke layar utama ini (seperti yang dijelaskan di bagian berikutnya di halaman ini).

Agar dapat mendukung gestur kembali prediktif, Anda harus mengupdate aplikasi menggunakan OnBackPressedCallback yang kompatibel dengan versi sebelumnya di AndroidX Activity 1.6.0 atau API yang lebih tinggi, atau menggunakan versi baru API platform OnBackInvokedCallback. Sebagian besar aplikasi menggunakan AndroidX API yang kompatibel dengan versi sebelumnya.

Update ini menyediakan jalur migrasi untuk menangkap navigasi kembali dengan benar, yang melibatkan penggantian intersepsi kembali dari KeyEvent.KEYCODE_BACK dan class apa pun dengan metode onBackPressed seperti Activity dan Dialog dengan Back API sistem yang baru.

Codelab dan video Google I/O

Selain menggunakan dokumentasi di halaman ini, coba codelab kami. Codelab ini menyediakan implementasi kasus penggunaan umum tentang WebView yang menangani gestur kembali prediktif menggunakan AndroidX Activity API.

Anda juga dapat melihat video Google I/O kami, yang mencakup contoh tambahan untuk mengimplementasikan AndroidX dan API platform.

Menangani gestur kembali kustom di Compose

Compose menyediakan composable PredictiveBackHandler untuk menangani gestur kembali kustom. API ini memungkinkan Anda merespons gestur kembali dan menyediakan Flow objek BackEventCompat yang dapat Anda gunakan untuk menerapkan animasi atau transisi kustom saat pengguna menggeser.

Untuk menggunakan PredictiveBackHandler, pastikan aplikasi Anda menyertakan dependensi androidx.activity:activity-compose (versi 1.8.0 atau yang lebih tinggi):

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}

PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress.
        }
        // Handle the final back action (e.g., navigate back).
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI.
    }
}
PredictiveBackSnippets.kt

Jika Anda hanya perlu mencegat gestur kembali tanpa melacak progres, gunakan BackHandler.

Mengupdate aplikasi yang menggunakan navigasi kembali default

Kembali prediktif diaktifkan secara default.

Jika aplikasi Anda menggunakan Fragment atau Komponen Navigasi, upgrade juga ke AndroidX Activity 1.6.0 atau yang lebih tinggi.

Mengupdate aplikasi yang menggunakan navigasi kembali kustom

Jika aplikasi Anda menerapkan perilaku kembali kustom, ada jalur migrasi yang berbeda, bergantung pada apakah aplikasi tersebut menggunakan AndroidX dan caranya menangani navigasi kembali.

Memigrasikan implementasi navigasi kembali AndroidX

Kasus penggunaan ini adalah yang paling umum (dan paling direkomendasikan). Ini berlaku untuk aplikasi baru atau yang sudah ada, yang menerapkan penanganan navigasi gestur khusus dengan OnBackPressedDispatcher, seperti yang dijelaskan dalam Menyediakan navigasi kembali khusus.

Untuk memastikan API yang sudah menggunakan OnBackPressedDispatcher (seperti Fragment dan Komponen Navigasi) berfungsi dengan lancar menggunakan gestur kembali prediktif, upgrade ke AndroidX Activity 1.6.0 atau yang lebih tinggi.

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

Memigrasikan aplikasi AndroidX yang berisi API navigasi kembali yang tidak didukung ke API AndroidX

Jika aplikasi Anda menggunakan library AndroidX, tetapi menerapkan atau membuat referensi ke API navigasi kembali yang tidak didukung, Anda harus bermigrasi untuk menggunakan API AndroidX untuk mendukung perilaku baru.

Untuk memigrasikan API yang tidak didukung ke API AndroidX:

1. Migrasikan logika penanganan Kembali sistem Anda ke OnBackPressedDispatcher AndroidX dengan implementasi OnBackPressedCallback. Untuk panduan mendetail, lihat Menyediakan navigasi kembali khusus.

2. Nonaktifkan OnBackPressedCallback saat siap menghentikan intersepsi gestur kembali.

3. Menghentikan intersepsi peristiwa kembali menggunakan OnBackPressed atau KeyEvent.KEYCODE_BACK.

4. Pastikan untuk mengupgrade ke AndroidX Activity 1.6.0 atau yang lebih tinggi.

   // In your build.gradle file:
   dependencies {
       // Add this in addition to your other dependencies
       implementation "androidx.activity:activity:1.6.0"
   }
   

Memilih untuk tidak menggunakan kembali prediktif

Untuk memilih tidak menggunakan, dalam AndroidManifest.xml di tag <application>, setel tanda android:enableOnBackInvokedCallback ke false.

<application
    ...
    android:enableOnBackInvokedCallback="false"
    ... >
...
</application>

Menyetelnya ke salah (false) akan melakukan hal berikut:

• Menonaktifkan sistem animasi gestur kembali prediktif.
• Mengabaikan OnBackInvokedCallback, tetapi panggilan OnBackPressedCallback tetap berfungsi.

Menonaktifkan pada tingkat aktivitas

Tanda android:enableOnBackInvokedCallback memungkinkan Anda menonaktifkan animasi sistem prediktif di tingkat aktivitas. Perilaku ini membuat proses migrasi aplikasi multi-aktivitas besar ke gestur kembali prediktif menjadi lebih mudah.

Kode berikut menunjukkan contoh enableOnBackInvokedCallback yang ditetapkan untuk mengaktifkan animasi sistem "kembali ke layar utama" dari MainActivity:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

Harap perhatikan hal-hal berikut saat menggunakan tanda android:enableOnBackInvokedCallback:

• Menyetel android:enableOnBackInvokedCallback=false akan menonaktifkan animasi kembali prediktif baik pada tingkat aktivitas maupun pada tingkat aplikasi, tergantung tempat Anda menetapkan tag. Setelan ini juga akan memerintahkan sistem untuk mengabaikan panggilan ke API platform OnBackInvokedCallback. Namun, panggilan ke OnBackPressedCallback akan terus berjalan karena OnBackPressedCallback kompatibel dengan versi lama dan memanggil onBackPressed API, yang tidak didukung sebelum Android 13.
• Menyetel tanda enableOnBackInvokedCallback pada tingkat aplikasi akan menetapkan nilai default untuk semua aktivitas di aplikasi. Anda dapat mengganti setelan default per aktivitas dengan menyetel tanda pada tingkat aktivitas, seperti yang ditunjukkan dalam contoh kode sebelumnya.

Panduan telepon balik

Ikuti panduan ini saat menggunakan callback kembali sistem yang didukung: PredictiveBackHandler atau BackHandler (untuk Compose), OnBackPressedCallback, atau OnBackInvokedCallback.

Menentukan Status UI yang mengaktifkan dan menonaktifkan setiap callback

Status UI adalah properti yang mendeskripsikan UI. Sebaiknya ikuti langkah-langkah tingkat tinggi ini.

1. Tentukan status UI yang mengaktifkan dan menonaktifkan setiap callback.

2. Tentukan status tersebut menggunakan jenis holder data yang dapat diamati, seperti StateFlow atau Status Compose, dan aktifkan atau nonaktifkan callback saat status berubah.

Jika aplikasi Anda sebelumnya mengaitkan logika kembali dengan pernyataan bersyarat, hal ini mungkin menandakan bahwa Anda bereaksi terhadap peristiwa kembali setelah peristiwa itu terjadi. Hindari pola ini dengan callback yang lebih baru. Jika memungkinkan, pindahkan callback ke luar pernyataan bersyarat dan kaitkan callback ke jenis holder data yang dapat diamati.

Menggunakan callback kembali sistem untuk Logika UI

Logika UI menentukan cara menampilkan UI. Gunakan callback kembali sistem untuk menjalankan logika UI, seperti menampilkan dialog atau menjalankan animasi.

Jika aplikasi Anda mengaktifkan OnBackPressedCallback atau OnBackInvokedCallback dengan PRIORITY_DEFAULT atau PRIORITY_OVERLAY, animasi kembali prediktif tidak akan berjalan dan Anda harus menangani peristiwa kembali. Jangan membuat callback ini untuk menjalankan logika bisnis atau untuk mencatat.

Gunakan pendekatan berikut jika aplikasi Anda harus menjalankan logika bisnis atau mencatat log saat pengguna menggeser kembali:

• Di Compose: Catat dalam callback onCleared() dari ViewModel yang terkait dengan tujuan Compose. Ini adalah sinyal terbaik untuk mengetahui kapan tujuan Compose dikeluarkan dari data sebelumnya dan dihancurkan.
• Di Android 16 dan yang lebih baru: Gunakan OnBackInvokedCallback dengan PRIORITY_SYSTEM_NAVIGATION_OBSERVER. Tindakan ini membuat callback pengamat yang tidak menggunakan peristiwa kembali. Misalnya, Anda dapat mendaftarkan callback ini saat pengguna menggeser kembali dari aktivitas root (keluar dari aplikasi Anda) untuk mencatat peristiwa kembali atau menjalankan logika bisnis sambil tetap mengizinkan animasi kembali ke layar utama diputar.
• Di aplikasi berbasis View: Catat dalam callback siklus proses atau data navigasi sebelumnya, bukan menggunakan peristiwa kembali:
  • Untuk transisi aktivitas, periksa apakah isFinishing adalah true dalam Activity.onDestroy().
  • Untuk transisi fragmen, periksa apakah isRemoving adalah true dalam siklus proses tampilan Fragmen onDestroy(), atau gunakan FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted).

Membuat callback tanggung jawab tunggal

Anda dapat menambahkan beberapa callback ke operator. Callback ditambahkan ke tumpukan tempat callback yang terakhir ditambahkan dan diaktifkan akan menangani gestur kembali berikutnya dengan satu callback per gestur kembali.

Lebih mudah mengelola status aktif callback jika callback tersebut memiliki tanggung jawab tunggal. Contoh:

Gambar 2 menunjukkan cara Anda dapat memiliki beberapa callback dalam stack, yang masing-masing bertanggung jawab atas satu hal. Di Compose, callback dievaluasi dari composable paling dalam ke paling luar, dan callback hanya berjalan jika callback yang mendahuluinya di stack dinonaktifkan:

• Dialog "Yakin ingin..." PredictiveBackHandler diaktifkan saat pengguna memasukkan data ke dalam formulir, dan dinonaktifkan jika tidak. Jika diaktifkan, fitur ini akan mencegat gestur kembali untuk menampilkan dialog konfirmasi atau animasi dalam aplikasi kustom.
• BackHandler tingkat layar berjalan jika callback sebelumnya dinonaktifkan. Dalam contoh ini, fitur tersebut dinonaktifkan.
• Callback NavHost menangani navigasi kembali untuk mengeluarkan tujuan dari back stack jika callback kustom sebelumnya dinonaktifkan.
• Terakhir, sistem menangani gestur kembali jika semua callback sebelumnya dinonaktifkan. Saat stack kembali berada di tujuan root-nya, sistem akan memicu animasi tingkat sistem seperti kembali ke layar utama, lintas aktivitas, dan lintas tugas.

Perilaku tumpukan yang sama berlaku di aplikasi berbasis View: OnBackPressedCallback yang terakhir ditambahkan dan diaktifkan akan diprioritaskan, dengan melakukan penggantian ke FragmentManager dan akhirnya penanganan kembali sistem.

Menguji animasi gestur kembali prediktif

Mulai Android 15, animasi sistem seperti kembali ke layar utama, lintas tugas, dan lintas aktivitas diaktifkan secara default untuk aplikasi yang mendukung navigasi kembali prediktif. Opsi ini tidak lagi berada di balik opsi developer.

Di perangkat yang menjalankan Android 13 atau Android 14, Anda dapat mengaktifkan opsi developer untuk menguji animasi kembali ke layar utama yang ditampilkan pada Gambar 1:

1. Di perangkat, buka Setelan > Sistem > Opsi developer.

2. Pilih Animasi kembali prediktif.

3. Luncurkan aplikasi yang telah diupdate, dan gunakan gestur kembali untuk melihat cara kerjanya.