navigationevent

  
La libreria Navigation Event fornisce un'API KMP-first per la gestione del pulsante Indietro del sistema e della funzionalità Indietro predittivo.
Ultimo aggiornamento Release stabile Candidato per la release Versione beta Alpha Release
30 luglio 2025 - - - 1.0.0-alpha05

Dichiarazione di dipendenze

Per aggiungere una dipendenza da navigationevent, devi aggiungere il Repository Maven di Google al tuo progetto. Per saperne di più, consulta il repository Maven di Google.

Aggiungi le dipendenze per gli artefatti che ti servono nel file build.gradle per la tua app o il tuo modulo:

Groovy

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

Kotlin

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

Per ulteriori informazioni sulle dipendenze, consulta Aggiungere dipendenze di build.

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Facci sapere se riscontri nuovi problemi o hai idee per migliorare questa libreria. Prima di crearne uno nuovo, dai un'occhiata ai problemi esistenti in questa libreria. Puoi aggiungere il tuo voto a un problema esistente facendo clic sul pulsante a forma di stella.

Creare un nuovo problema

Per ulteriori informazioni, consulta la documentazione di Issue Tracker.

Non sono disponibili note di rilascio per questo artefatto.

Versione 1.0

Versione 1.0.0-alpha05

30 luglio 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha05 viene ritirata. La versione 1.0.0-alpha05 contiene questi commit.

Supporto della gerarchia padre-figlio:

Un NavigationEventDispatcher ora può avere dispatcher principali e secondari, formando una struttura ad albero gerarchica. In questo modo, gli eventi di navigazione possono propagarsi ed essere gestiti in modo più flessibile nei componenti UI complessi di Compose riflettendo la gerarchia strutturale della UI tramite dispatcher concatenati. (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)

La proprietà gerarchica isEnabled consente il controllo dall'alto verso il basso di un dispatcher. Quando isEnabled è impostato su false in un dispatcher, tutti i dispatcher secondari vengono disattivati automaticamente. Questa funzionalità consente di disattivare in modo efficiente interi rami del sistema di eventi di navigazione. (I9e985)

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

Inoltre, la proprietà isEnabled su NavigationEventCallback ora rispetta lo stato di attivazione del dispatcher associato. Ciò significa che un callback viene considerato abilitato solo se sono abilitati sia il callback stesso sia il relativo dispatcher (inclusi i relativi antenati), garantendo un controllo gerarchico coerente sull'attivazione del 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()

È stato introdotto un nuovo metodo dispose() per la pulizia corretta dei dispatcher e dei relativi processi secondari. La chiamata dispose() interrompe gli ascoltatori per evitare perdite di memoria, elimina in modo ricorsivo tutti i dispatcher secondari, rimuove tutti i callback registrati nel dispatcher e lo scollega dal relativo dispatcher principale. In questo modo, le risorse vengono rilasciate correttamente quando i dispatcher non sono più necessari. (I9e985)

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

Se viene chiamato un metodo pubblico su un dispatcher eliminato, viene generata immediatamente un'eccezione IllegalStateException. In questo modo si evitano errori silenziosi e si aiuta gli sviluppatori a identificare un utilizzo improprio durante lo sviluppo. (Ic2dc3)

  val callback2 = TestNavigationEventCallback()

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

Nota:introdurremo un nuovo NavigationEventDispatcherOwner composable che gestisce automaticamente un dispatcher secondario all'interno della UI di Compose in aosp/3692572. Tuttavia, questa modifica non è stata inclusa nel taglio della release attuale ed è prevista per la prossima.

Libreria di test di navigazione

  • Aggiungi il modulo navigationevent-testing per fornire utilità di test dedicate per la libreria navigationevent. (0e50b6)
  • Aggiungi la classe di utilità fittizia TestNavigationEventCallback per i test. Registra le chiamate del metodo di callback e memorizza gli elementi NavigationEvent ricevuti per supportare la verifica. (4a0246)
  • Aggiungi la funzione di utilità fittizia TestNavigationEvent per creare istanze NavigationEvent con valori predefiniti, semplificando i test unitari per l'elaborazione degli eventi di navigazione. (3b63f5)
  • Aggiungi la classe di utilità fittizia TestNavigationEventDispatcherOwner per i test. Monitora i conteggi degli eventi di fallback e di modifica dello stato abilitato per supportare la verifica dell'interazione nei test. (c8753e)

Modifiche alle API

  • Sposta NavigationEventInputHandler da androidMain a commonMain per renderlo disponibile nel codice comune KMP. Aggiungi nuovi metodi public send* per l'invio degli eventi. Modifica le funzioni di distribuzione su NavigationEventDispatcher da public a internal; ora gli utenti devono utilizzare NavigationEventInputHandler per inviare eventi. (Ia7114)
  • Rinomina NavigationInputHandler in OnBackInvokedInputHandler. (I63405)

Correzioni di bug

  • Refactor NavigationEventDispatcher per ridurre l'overhead evitando allocazioni di elenchi intermedi e migliorando le prestazioni di distribuzione dei callback. (I82702, I1a9d9)
  • Aggiungi annotazioni @FloatRange ai campi touchX, touchY e progress in NavigationEvent per applicare intervalli di valori validi in fase di compilazione e migliorare la sicurezza dell'API. (Iac0ec)

Versione 1.0.0-alpha04

2 luglio 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha04 viene ritirata. La versione 1.0.0-alpha04 contiene questi commit.

Correzioni di bug

  • Utilizzato implementedInJetBrainsFork per navigationevent-compose e aggiunto un target commonStubs per rispettare le convenzioni di Compose. Modifica richiesta da JetBrains. (f60c79)
  • È stata corretta l'applicazione del plug-in del compilatore Compose per Kotlin/Native per garantire la corretta generazione di stub. Nessun impatto sulle API pubbliche o sul comportamento. (1890c9)

Versione 1.0.0-alpha03

18 giugno 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha03 viene ritirata. La versione 1.0.0-alpha03 contiene questi commit.

Nuove funzionalità

  • È stato introdotto un nuovo modulo navigationevent-compose per supportare le funzionalità di Jetpack Compose nella libreria navigationevent. (980d78)
  • NavigationEvent Compose ha aggiunto una nuova composizione locale LocalNavigationEventDispatcherOwner. Restituisce un valore Nullable per determinare meglio se è disponibile nella composizione corrente. NavigationEventHandler ora genererà un errore se il proprietario sottostante non viene trovato. (62ffda)
  • NavigationEvent Compose ha aggiunto un nuovo NavigationEventHandler composable per gestire gli eventi (gesto Indietro predittivo). Fornisce un Flow di NavigationEvent oggetti che devono essere raccolti nella lambda di sospensione che fornisci 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
  }
}

Modifiche alle API

  • Ogni NavigationEventCallback ora può essere registrato con un solo NavigationEventDispatcher alla volta; l'aggiunta a più dispatcher genera un IllegalStateException. Tieni presente che questo comportamento è diverso da OnBackPressedDispatcher, che consente più dispatcher. (e82c19)
  • È stato creato isPassThrough un val per impedire la mutazione durante la navigazione, che potrebbe interrompere l'invio di NavigationEvent. (I0b287)

Versione 1.0.0-alpha02

4 giugno 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha02 viene ritirata. La versione 1.0.0-alpha02 contiene questi commit.

Modifiche alle API

  • Sostituisci il costruttore secondario di NavigationEventDispatcher con gli argomenti predefiniti. (I716a0)
  • Rimuovi la proprietà prioritaria da NavigationEventCallback. Trasferisci la priorità a NavigationEventDispatcher.addCallback(). (I13cae)

Correzioni di bug

  • È stato corretto un ConcurrentModificationException che poteva verificarsi quando veniva chiamato NavigationEventCallback.remove() a causa della modifica simultanea dell'elenco interno degli elementi chiudibili. (b/420919815)

Versione 1.0.0-alpha01

20 maggio 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha01 viene ritirata. La versione 1.0.0-alpha01 contiene questi commit.

Nuove funzionalità

  • La libreria androidx.navigationevent fornisce un'API KMP-first per la gestione del pulsante Indietro del sistema e di Predictive Back. NavigationEventDispatcher funge da API comuni per registrare una o più istanze di NavigationEventCallback per la ricezione di eventi di sistema indietro.
  • Questo livello si trova sotto le API rilasciate in precedenza in androidx.activity e mira a essere un sostituto meno soggettivo per l'utilizzo delle API Activity nei componenti di livello superiore o per l'utilizzo diretto delle API del framework Android OnBackInvokedDispatcher. Le API androidx.activity sono state riscritte in base alle API Navigation Event nell'ambito di Activity 1.12.0-alpha01.