navigationevent

  
Library Peristiwa Navigasi menyediakan API yang mengutamakan KMP untuk menangani kembali sistem serta Kembali Prediktif.
Update Terbaru Rilis Stabil Kandidat Rilis Rilis Beta Rilis Alfa
13 Agustus 2025 - - - 1.0.0-alpha06

Mendeklarasikan dependensi

Untuk menambahkan dependensi pada navigationevent, Anda harus menambahkan repositori Maven Google ke project Anda. Baca repositori Maven Google untuk mengetahui informasi selengkapnya.

Tambahkan dependensi untuk artefak yang diperlukan dalam file build.gradle bagi aplikasi atau modul Anda:

Groovy

dependencies {
    implementation "androidx.navigationevent:navigationevent:1.0.0-alpha06"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.0.0-alpha06")
}

Untuk informasi dependensi selengkapnya, lihat Menambahkan dependensi build.

Masukan

Masukan Anda membantu meningkatkan kualitas Jetpack. Beri tahu kami jika Anda menemukan masalah baru atau mempunyai masukan untuk meningkatkan kualitas library ini. Harap periksa masalah yang sudah diketahui dalam library ini sebelum membuat laporan baru. Anda dapat memberikan suara untuk masalah yang sudah diketahui dengan mengklik tombol bintang.

Laporkan masalah baru

Lihat dokumentasi Issue Tracker untuk informasi selengkapnya.

Tidak ada catatan rilis untuk artefak ini.

Versi 1.0

Versi 1.0.0-alpha06

13 Agustus 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha06 dirilis. Versi 1.0.0-alpha06 berisi commit ini.

Fitur Baru

Passive Listeners API

Anda kini dapat meneruskan informasi kontekstual kustom dari host navigasi mana pun dan memproses perubahan status gestur secara pasif dari mana saja di UI Anda. Hal ini memungkinkan animasi yang sesuai konteks untuk kembali prediktif dan navigasi berbasis gestur lainnya.

Fitur ini memiliki dua bagian:

  1. Memberikan Info - Gunakan NavigationEventInfo untuk membawa data kustom.
  2. Menggunakan Status - Gunakan dispatcher.state (NavigationEventState) untuk mengamati progres dan konteks gestur.
  • NavigationEventCallback kini mengekspos metode setInfo(currentInfo, previousInfo) untuk menyetel konteks gestur dalam satu panggilan (I1d5e7, b/424470518).
  • NavigationEventHandler menambahkan kelebihan beban baru yang menerima currentInfo dan previousInfo, sehingga menjadikannya API utama untuk menyediakan konteks di aplikasi Compose (I6ecd3, b/424470518).

Contoh:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • NavigationEventDispatcher kini mengekspos dispatcher.state dan dispatcher.getState<T>() (If7fae, Ia90ca, b/424470518). API berbasis StateFlow ini memungkinkan UI mengamati progres gestur dan data kontekstual tanpa menangani peristiwa secara langsung.

Contoh:

  val gestureState by LocalNavigationEventDispatcherOwner.current!!
      .navigationEventDispatcher
      .state
      .collectAsState()

  val progress = gestureState.progress // Returns latestEvent.progress or 0F

  when (val state = gestureState) {
      is InProgress -> {
          val toScreen = state.currentInfo as MyScreenInfo
          val fromScreen = state.previousInfo as MyScreenInfo
          println("Navigating from ${fromScreen.screenName} to ${toScreen.screenName}")
      }
      is Idle -> { /* Idle state */ }
  }

  • Menambahkan properti progress ke NavigationEventState (I7b196) yang menampilkan latestEvent.progress saat sedang berlangsung, atau 0F jika tidak:

    val progress = state.progress

  • Tambahkan composable NavigationEventDispatcherOwner untuk membuat, menautkan, dan menghapus instance NavigationEventDispatcher secara hierarkis. Aktifkan kontrol dinamis status aktif dispatcher dan pembersihan otomatis.

    @Composable
fun Sample() {
    NavigationEventDispatcherOwner(enabled = true) {
        val localDispatcherOwner = LocalNavigationEventDispatcherOwner.current
    }
}

Perubahan API

  • Parameter isPassthrough telah dihapus dari NavigationEventCallback. (I99028, b/424470518)
  • Konstruktor NavigationEventState kini bersifat internal. Untuk pengujian, perbarui status (defaultnya Idle) melalui DirectNavigationEventInputHandler. Panggil handleOnStarted atau handleOnProgressed untuk menyetel status ke InProgress, dan handleOnCompleted atau handleOnCancelled untuk mengembalikannya ke Idle. Untuk mengupdate NavigationEventInfo, gunakan NavigationEventCallback.setInfo. (I93dca, b/424470518)
  • Menambahkan parameter default ke NavigationEvent untuk mempermudah instansiasi dan menyederhanakan pengujian yang harus digunakan sebagai pengganti TestNavigationEvent. (I5dc49, I232f4)
  • Menambahkan TestNavigationEventCallback untuk menguji peristiwa navigasi dengan status saat ini/sebelumnya tertentu. (Idd22e, b/424470518)
  • NavigationEventInputHandler telah dijadikan class abstrak untuk menggantikan AbstractNavigationEventInputHandler sebelumnya dengan implementasi di DirectNavigationEventInputHandler (Iadde5, Ifed40I3897c, b/432616296, b/435416924)
  • Fungsi send* di NavigationEventInputHandler telah diganti nama awalan menjadi handle*. (Iffcaf)
  • OnBackInvokedInputHandler sekarang memperluas NavigationInputHandler abstract yang baru. (Ib45aa)
  • Mengubah NavigationEventDispatcherOwner untuk mewajibkan dispatcher induk tempat Anda harus meneruskan null secara eksplisit untuk membuat dispatcher root. (Ia6f64, b/431534103)

Perbaikan Bug

  • Meningkatkan efisiensi dengan menghindari salinan koleksi di NavigationEventDispatcher.dispose(). (I4ab09)
  • Memperbaiki masalah saat NavigationEventHandler tidak merespons dengan benar perubahan pada status aktifnya. (Ia5268,I19bec, I5be5c, b/431534103)

Info Terbaru Dokumen

  • KDocs untuk NavigationEvent diperluas untuk mengklarifikasi perannya sebagai wrapper peristiwa terpadu dan perilaku properti detail di berbagai jenis navigasi (gestur, klik). (I91e8d)
  • Memperbarui dokumentasi untuk API penanganan kembali sistem Compose (BackHandler, PredictiveBackHandler, NavigationEventHandler) untuk menjelaskan perilaku secara khusus terkait urutan callback. (I7ab94, )

Pembaruan Dependensi

  • NavigationEvent kini bergantung pada Compose Runtime 1.9.0-beta03 yang memungkinkan artefak navigationevent-compose mendukung semua target KMP. (Ia1b87)

Versi 1.0.0-alpha05

30 Juli 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha05 dirilis. Versi 1.0.0-alpha05 berisi commit ini.

Dukungan Hierarki Induk-Turunan:

NavigationEventDispatcher kini dapat memiliki dispatcher induk dan turunan, yang membentuk struktur pohon hierarkis. Hal ini memungkinkan peristiwa navigasi untuk dipropagasi dan dikelola secara lebih fleksibel di seluruh komponen UI Compose yang kompleks dengan mencerminkan hierarki struktural UI melalui dispatcher berantai. (I194ac)

  // Create a parent dispatcher that will manage navigation events at a higher level.
  val parentDispatcher = NavigationEventDispatcher()

  // Create a child dispatcher linked to the parent, forming a hierarchy.
  val childDispatcher = NavigationEventDispatcher(parentDispatcher)

Properti isEnabled hierarkis memungkinkan kontrol dispatcher dari atas ke bawah. Jika isEnabled ditetapkan ke false pada dispatcher, semua dispatcher turunannya akan otomatis dinonaktifkan. Fitur ini memungkinkan seluruh cabang sistem peristiwa navigasi dinonaktifkan secara efisien. (I9e985)

  // Disabling the child dispatcher disables all its callbacks and any of its children recursively.
  childDispatcher.isEnabled = false

Selain itu, properti isEnabled di NavigationEventCallback kini mematuhi status aktif dispatcher terkait. Artinya, callback dianggap diaktifkan hanya jika callback itu sendiri dan dispatchernya (termasuk ancestor-nya) diaktifkan, sehingga memastikan kontrol hierarkis yang konsisten atas aktivasi callback. (I1799a)

  // Create a test callback and add it to the child dispatcher.
  val callback1 = TestNavigationEventCallback(isEnabled = true)
  childDispatcher.addCallback(callback1)

  // Since the childDispatcher is disabled, the callback is effectively disabled as well.
  assertThat(callback1.isEnabled).isFalse()

Metode dispose() baru telah diperkenalkan untuk pembersihan yang tepat pada dispatcher dan turunannya. Memanggil dispose() akan menghentikan pemroses untuk mencegah kebocoran memori, membuang semua dispatcher turunan secara rekursif, menghapus semua callback yang terdaftar ke dispatcher, dan membatalkan tautannya dari induknya. Hal ini menjamin resource dilepaskan dengan benar saat dispatcher tidak lagi diperlukan. (I9e985)

  // Dispose the child dispatcher to clean up resources.
  childDispatcher.dispose()

Jika ada metode publik yang dipanggil pada dispatcher yang dihapus, IllegalStateException akan segera ditampilkan. Hal ini mencegah kegagalan senyap dan membantu developer mengidentifikasi penggunaan yang tidak tepat selama pengembangan. (Ic2dc3)

  val callback2 = TestNavigationEventCallback()

  // Attempting to use a disposed dispatcher will throw an exception.
  assertThrows<IllegalStateException> {
      childDispatcher.addCallback(callback2)
  }

Catatan: Kami akan memperkenalkan Composable NavigationEventDispatcherOwner baru yang otomatis mengelola dispatcher turunan dalam UI Compose di aosp/3692572. Namun, perubahan ini tidak masuk dalam rilis saat ini dan direncanakan untuk rilis berikutnya.

Navigation Testing Library

  • Menambahkan modul navigationevent-testing untuk menyediakan utilitas pengujian khusus untuk library navigationevent. (0e50b6)
  • Menambahkan class utilitas palsu TestNavigationEventCallback untuk pengujian. Objek ini mencatat panggilan metode callback dan menyimpan item NavigationEvent yang diterima untuk mendukung verifikasi. (4a0246)
  • Tambahkan fungsi utilitas tiruan TestNavigationEvent untuk membuat instance NavigationEvent dengan nilai default, sehingga menyederhanakan pengujian unit untuk pemrosesan peristiwa navigasi. (3b63f5)
  • Menambahkan class utilitas palsu TestNavigationEventDispatcherOwner untuk pengujian. Ini melacak jumlah peristiwa penggantian dan perubahan status yang diaktifkan untuk mendukung verifikasi interaksi dalam pengujian. (c8753e)

Perubahan API

  • Pindahkan NavigationEventInputHandler dari androidMain ke commonMain agar tersedia di kode umum KMP. Menambahkan metode public send* baru untuk mengirimkan peristiwa. Ubah fungsi pengiriman di NavigationEventDispatcher dari public menjadi internal; pengguna kini harus menggunakan NavigationEventInputHandler untuk mengirim peristiwa. (Ia7114)
  • Mengganti nama NavigationInputHandler menjadi OnBackInvokedInputHandler. (I63405)

Perbaikan Bug

  • Memfaktorkan ulang NavigationEventDispatcher untuk mengurangi overhead dengan menghindari alokasi daftar perantara dan meningkatkan performa pengiriman callback. (I82702, I1a9d9)
  • Menambahkan anotasi @FloatRange ke kolom touchX, touchY, dan progress di NavigationEvent untuk menerapkan rentang nilai yang valid pada waktu kompilasi dan meningkatkan keamanan API. (Iac0ec)

Versi 1.0.0-alpha04

2 Juli 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha04 dirilis. Versi 1.0.0-alpha04 berisi commit ini.

Perbaikan Bug

  • Menggunakan implementedInJetBrainsFork untuk navigationevent-compose dan menambahkan target commonStubs agar sesuai dengan konvensi Compose. Perubahan yang diminta oleh JetBrains. (f60c79)
  • Memperbaiki penerapan plugin compiler Compose untuk Kotlin/Native guna memastikan pembuatan stub yang benar. Tidak ada dampak pada API atau perilaku publik. (1890c9)

Versi 1.0.0-alpha03

18 Juni 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha03 dirilis. Versi 1.0.0-alpha03 berisi commit ini.

Fitur Baru

  • Memperkenalkan modul navigationevent-compose baru untuk mendukung fitur Jetpack Compose di library navigationevent. (980d78)
  • NavigationEvent Compose telah menambahkan komposisi lokal LocalNavigationEventDispatcherOwner baru. Metode ini menampilkan nilai nullable untuk menentukan secara lebih baik apakah nilai tersebut tersedia dalam komposisi saat ini. NavigationEventHandler kini akan menampilkan error jika pemilik dasar tidak ditemukan. (62ffda)
  • Compose NavigationEvent telah menambahkan Composable NavigationEventHandler baru untuk menangani peristiwa (gestur kembali prediktif). Fungsi ini menyediakan Flow objek NavigationEvent yang harus dikumpulkan dalam lambda penangguhan yang Anda berikan c42ba6 :
NavigationEventHandler { progress: Flow<NavigationEvent> ->
  // This block is executed when the back gesture begins.
  try {
    progress.collect { backEvent ->
      // Handle gesture progress updates here.
    }
    // This block is executed if the gesture completes successfully.
  } catch (e: CancellationException) {
    // This block is executed if the gesture is cancelled
    throw e
  } finally {
    // This block is executed either the gesture is completed or cancelled
  }
}

Perubahan API

  • Setiap NavigationEventCallback kini hanya dapat didaftarkan dengan satu NavigationEventDispatcher dalam satu waktu; menambahkannya ke beberapa pengirim akan memunculkan IllegalStateException. Perhatikan bahwa perilaku ini berbeda dengan OnBackPressedDispatcher, yang memungkinkan beberapa dispatcher. (e82c19)
  • Menjadikan isPassThrough sebagai val untuk mencegah mutasi selama navigasi, yang dapat merusak pengiriman NavigationEvent. (I0b287)

Versi 1.0.0-alpha02

4 Juni 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha02 dirilis. Versi 1.0.0-alpha02 berisi commit ini.

Perubahan API

  • Ganti konstruktor sekunder NavigationEventDispatcher dengan argumen default. (I716a0)
  • Hapus properti prioritas dari NavigationEventCallback. Teruskan prioritas ke NavigationEventDispatcher.addCallback() sebagai gantinya. (I13cae)

Perbaikan Bug

  • Memperbaiki ConcurrentModificationException yang dapat terjadi saat NavigationEventCallback.remove() dipanggil karena memodifikasi daftar internal objek yang dapat ditutup secara bersamaan. (b/420919815)

Versi 1.0.0-alpha01

20 Mei 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha01 dirilis. Versi 1.0.0-alpha01 berisi commit ini.

Fitur Baru

  • Library androidx.navigationevent menyediakan API yang mengutamakan KMP untuk menangani kembali sistem serta Kembali Prediktif. NavigationEventDispatcher berfungsi sebagai API umum untuk mendaftarkan satu atau beberapa instance NavigationEventCallback untuk menerima peristiwa kembali sistem.
  • Lapisan ini berada di bawah API yang dirilis sebelumnya di androidx.activity dan bertujuan untuk menjadi pengganti yang lebih tidak berpihak untuk menggunakan API Aktivitas di komponen tingkat yang lebih tinggi atau langsung menggunakan API OnBackInvokedDispatcher framework Android. API androidx.activity telah ditulis ulang di atas Navigation Event API sebagai bagian dari Activity 1.12.0-alpha01.