Halaman ini diterjemahkan oleh Cloud Translation API.

Menambahkan dukungan untuk gestur kembali prediktif

**Gambar 1.** Mockup tampilan dan nuansa gestur kembali prediktif di ponsel

Kembali Prediktif, fitur navigasi gestur, memungkinkan pengguna melihat pratinjau tempat geser kembali membawa mereka.

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 secara keseluruhan atau di tingkat aktivitas.

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

Agar dapat mendukung gestur kembali prediktif, Anda harus mengupdate aplikasi menggunakan OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) yang kompatibel dengan versi sebelumnya 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.

Mengupdate aplikasi yang menggunakan navigasi kembali default

Mengupdate aplikasi untuk mendukung fitur ini dapat dilakukan dengan mudah jika aplikasi Anda tidak menerapkan perilaku kembali khusus (dengan kata lain, aplikasi akan menyerahkan penanganan kembali kepada sistem). Pilih untuk menggunakan fitur ini seperti yang dijelaskan dalam panduan ini.

Jika aplikasi Anda menggunakan Fragment atau Komponen Navigasi, upgrade juga ke AndroidX Activity 1.6.0-alpha05 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.

Aplikasi Anda menggunakan AndroidX	Cara aplikasi Anda menangani navigasi kembali	Jalur migrasi yang direkomendasikan (link di halaman ini)
Ya	API AndroidX	Memigrasikan implementasi kembali AndroidX yang ada
Ya	API platform yang tidak didukung	Memigrasikan aplikasi AndroidX yang berisi API navigasi kembali yang tidak didukung ke API AndroidX
Tidak	API platform yang tidak didukung, dapat dimigrasikan	Memigrasikan aplikasi yang menggunakan API navigasi kembali yang tidak didukung ke API platform
Tidak	API platform tidak didukung, tetapi tidak dapat dimigrasikan	Tunda persetujuan hingga fitur ini diperlukan

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.

Jika aplikasi Anda sesuai dengan kategori ini, ikuti langkah-langkah berikut untuk menambahkan dukungan bagi gestur kembali prediktif:

Untuk memastikan API yang sudah menggunakan API OnBackPressedDispatcher (seperti Fragment dan Komponen Navigasi) berfungsi dengan lancar menggunakan gestur kembali prediktif, upgrade ke AndroidX Activity 1.6.0-alpha05.
```
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```
Pilih untuk menggunakan gestur kembali prediktif, seperti yang dijelaskan di halaman ini.

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:

Migrasikan logika penanganan Kembali sistem Anda ke OnBackPressedDispatcher AndroidX dengan implementasi OnBackPressedCallback. Untuk panduan mendetail, lihat Menyediakan navigasi kembali khusus.
Nonaktifkan OnBackPressedCallback saat siap menghentikan intersepsi gestur kembali.
Menghentikan intersepsi peristiwa kembali melalui OnBackPressed atau KeyEvent.KEYCODE_BACK.

Pastikan untuk mengupgrade ke AndroidX Activity 1.6.0-alpha05.

// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"

Setelah berhasil memigrasikan aplikasi Anda, pilih untuk menggunakan gestur kembali prediktif (seperti yang dijelaskan di halaman ini) untuk melihat animasi sistem "kembali ke layar utama".

Catatan: OnBackPressedCallback selalu dipanggil, apa pun nilai android:enableOnBackInvokedCallback. Dengan kata lain, menonaktifkan sistem animasi tidak akan memengaruhi logika penanganan kembali aplikasi jika menggunakan OnBackPressedCallback.

Memigrasikan aplikasi yang menggunakan API navigasi kembali yang tidak didukung ke API platform

Jika aplikasi Anda tidak dapat menggunakan library AndroidX dan sebagai gantinya mengimplementasikan atau membuat referensi ke navigasi Kembali kustom menggunakan API yang tidak didukung, Anda harus bermigrasi ke API platform OnBackInvokedCallback.

Selesaikan langkah-langkah berikut untuk memigrasikan API yang tidak didukung ke API platform:

Gunakan OnBackInvokedCallback API baru di perangkat yang menjalankan Android 13 atau versi lebih baru, dan manfaatkan API yang tidak didukung di perangkat yang menjalankan Android 12 atau versi lebih lama.
Daftarkan logika kembali kustom Anda di OnBackInvokedCallback dengan onBackInvokedDispatcher. Langkah ini akan mencegah aktivitas saat ini diselesaikan, dan callback Anda akan mendapat kesempatan untuk bereaksi terhadap tindakan Kembali setelah pengguna menyelesaikan navigasi Kembali sistem.

Batalkan pendaftaran OnBackInvokedCallback saat siap menghentikan intersepsi gestur kembali. Jika tidak, pengguna mungkin akan melihat perilaku yang tidak diinginkan saat menggunakan navigasi Kembali sistem—misalnya, "terhenti" di antara tampilan dan memaksa mereka untuk menghentikan paksa aplikasi Anda.

Berikut contoh cara memigrasikan logika dari onBackPressed:

Kotlin

@Override
fun onCreate() {
    if (BuildCompat.isAtLeastT()) {
        onBackInvokedDispatcher.registerOnBackInvokedCallback(
            OnBackInvokedDispatcher.PRIORITY_DEFAULT
        ) {
            /**
             * onBackPressed logic goes here. For instance:
             * Prevents closing the app to go home screen when in the
             * middle of entering data to a form
             * or from accidentally leaving a fragment with a WebView in it
             *
             * Unregistering the callback to stop intercepting the back gesture:
             * When the user transitions to the topmost screen (activity, fragment)
             * in the BackStack, unregister the callback by using
             * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
             * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
             */
        }
    }
}

Java

@Override
void onCreate() {
  if (BuildCompat.isAtLeastT()) {
    getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
        OnBackInvokedDispatcher.PRIORITY_DEFAULT,
        () -> {
          /**
           * onBackPressed logic goes here - For instance:
           * Prevents closing the app to go home screen when in the
           * middle of entering data to a form
           * or from accidentally leaving a fragment with a WebView in it
           *
           * Unregistering the callback to stop intercepting the back gesture:
           * When the user transitions to the topmost screen (activity, fragment)
           * in the BackStack, unregister the callback by using
           * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
           * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
           */
        }
    );
  }
}

Menghentikan intersepsi peristiwa kembali melalui OnBackPressed atau KeyEvent.KEYCODE_BACK untuk Android 13 dan yang lebih baru.
Setelah berhasil memigrasikan aplikasi Anda, pilih untuk menggunakan gestur kembali prediktif (seperti yang dijelaskan di halaman ini) sehingga OnBackInvokedCallback dapat diterapkan.

Anda dapat mendaftarkan OnBackInvokedCallback dengan PRIORITY_DEFAULT atau PRIORITY_OVERLAY, yang tidak tersedia di OnBackPressedCallback AndroidX yang serupa. Mendaftarkan callback dengan PRIORITY_OVERLAY akan membantu dalam beberapa kasus.

Hal ini berlaku saat Anda bermigrasi dari onKeyPreIme() dan callback perlu menerima gestur kembali, bukan IME terbuka. IME mendaftarkan callback dengan PRIORITY_DEFAULT saat dibuka. Daftarkan callback Anda ke PRIORITY_OVERLAY untuk memastikan OnBackInvokedDispatcher mengirim gestur kembali ke callback Anda, bukan IME terbuka.

Memilih untuk menggunakan gestur kembali prediktif

Setelah menentukan cara mengupdate aplikasi berdasarkan kasus Anda, pilih untuk mendukung gestur kembali prediktif.

Untuk memilih mendukung, dalam AndroidManifest.xml di tag <application>, setel tanda android:enableOnBackInvokedCallback ke true.

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

Jika Anda tidak memberikan nilai, nilai tersebut akan disetel sebagai default ke false dan melakukan hal berikut:

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

Memilih menggunakan pada tingkat aktivitas

Mulai Android 14, tanda android:enableOnBackInvokedCallback memungkinkan Anda menggunakan animasi sistem prediktif pada tingkat aktivitas. Perilaku ini membuat proses migrasi aplikasi multi-aktivitas besar ke gestur kembali prediktif menjadi lebih mudah. Dengan Android 15, kembali prediktif tidak lagi berada di balik opsi developer. Aplikasi dapat memilih untuk mengaktifkan kembali prediktif sepenuhnya atau di level aktivitas.

Kode berikut menunjukkan contoh penggunaan enableOnBackInvokedCallback 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>

Pada contoh sebelumnya, menyetel android:enableOnBackInvokedCallback=true untuk ".SecondActivity" akan mengaktifkan animasi sistem lintas aktivitas.

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.

Praktik terbaik callback

Berikut adalah praktik terbaik untuk menggunakan callback kembali sistem yang didukung; 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.

Tentukan status UI yang mengaktifkan dan menonaktifkan setiap callback.
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 pop-up atau menjalankan animasi.

Jika aplikasi Anda mengaktifkan callback kembali sistem, animasi prediktif tidak akan berjalan, dan Anda harus menangani peristiwa kembali. Jangan membuat callback hanya untuk menjalankan logika non-UI.

Misalnya, jika Anda menghentikan peristiwa kembali hanya untuk mencatat, sebaiknya catat dalam siklus proses Aktivitas atau Fragmen saja.

Untuk kasus aktivitas ke aktivitas atau kasus fragmen ke aktivitas, catat jika isFinishing dalam onDestroy adalah true dalam siklus proses Aktivitas.
Untuk kasus fragmen ke fragmen, catat jika isRemoving dalam onDestroy bernilai benar dalam siklus proses tampilan Fragmen. Atau, catat menggunakan metode onBackStackChangeStarted atau onBackStackChangeCommitted dalam FragmentManager.OnBackStackChangedListener.

Untuk kasus 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.

Membuat callback tanggung jawab tunggal

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

Lebih mudah untuk mengelola status callback yang diaktifkan jika callback tersebut memiliki satu tanggung jawab. Contoh:

Pengurutan callback dalam stack. — **Gambar 2.** Diagram stack callback.

Gambar 2 menunjukkan bagaimana Anda dapat memiliki beberapa callback dalam stack, masing-masing bertanggung jawab untuk satu hal. Callback hanya berjalan jika callback di atasnya dalam stack dinonaktifkan. Dalam contoh ini, callback "Yakin..." diaktifkan saat pengguna memasukkan data ke dalam formulir, dan dinonaktifkan jika tidak. Callback akan membuka dialog konfirmasi saat pengguna menggeser kembali untuk keluar dari formulir.

Callback lainnya dapat mencakup komponen material yang mendukung kembali prediktif, transisi AndroidX menggunakan Progress API, atau callback kustom lainnya.

Callback childFragmentManager berjalan jika callback di atas dinonaktifkan dan data sebelumnya untuk FragmentManager ini tidak kosong, dengan childFragmentManager dilampirkan dalam Fragment. Dalam contoh ini, callback internal ini dinonaktifkan.

Demikian pula, callback internal supportFragmentManager akan berjalan jika callback di atas dinonaktifkan dan stack-nya tidak kosong. Perilaku ini konsisten saat menggunakan FragmentManager atau NavigationComponent untuk navigasi, karena NavigationComponent bergantung pada FragmentManager. Dalam contoh ini, callback ini berjalan jika pengguna tidak memasukkan teks ke dalam formulir yang menyebabkan callback "Are you sure..." dinonaktifkan.

Terakhir, super.onBackPressed() adalah callback tingkat sistem, yang lagi-lagi berjalan jika callback di atas dinonaktifkan. Untuk memicu animasi sistem seperti kembali ke layar utama, lintas aktivitas, dan lintas tugas, data sebelumnya supportFragmentManager harus kosong sehingga callback internalnya dinonaktifkan.

Menguji animasi gestur kembali prediktif

Jika masih menggunakan Android 13 atau Android 14, Anda dapat menguji animasi "kembali ke layar utama" yang ditunjukkan pada Gambar 1.

Untuk menguji animasi ini, selesaikan langkah-langkah berikut:

Di perangkat, buka Setelan > Sistem > Opsi developer.
Pilih Animasi kembali prediktif.
Luncurkan aplikasi yang telah diupdate, dan gunakan gestur kembali untuk melihat cara kerjanya.