navigationevent

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:

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

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

Per saperne di più sulle dipendenze, consulta Aggiungi 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.

Crea 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-alpha06

13 agosto 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha06 viene rilasciata. La versione 1.0.0-alpha06 contiene questi commit.

Nuove funzionalità

API Passive Listeners

Ora puoi trasmettere informazioni contestuali personalizzate da qualsiasi host di navigazione e ascoltare passivamente le modifiche dello stato dei gesti da qualsiasi punto dell'interfaccia utente. Ciò consente animazioni sensibili al contesto per il gesto Indietro predittivo e altre navigazioni basate su gesti.

Questa funzionalità è composta da due parti:

1. Providing Info: utilizza NavigationEventInfo per trasferire dati personalizzati.
2. Stato di consumo: utilizza dispatcher.state (NavigationEventState) per osservare l'avanzamento e il contesto del gesto.

• NavigationEventCallback ora espone il metodo setInfo(currentInfo, previousInfo) per impostare il contesto dei gesti in una sola chiamata (I1d5e7, b/424470518).
• NavigationEventHandler aggiunge un nuovo overload che accetta currentInfo e previousInfo, rendendola l'API principale per fornire il contesto nelle app Compose (I6ecd3, b/424470518).

Esempio:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }

• NavigationEventDispatcher ora espone dispatcher.state e dispatcher.getState<T>() (If7fae, Ia90ca, b/424470518). Queste API basate su StateFlow consentono a qualsiasi UI di osservare l'avanzamento dei gesti e i dati contestuali senza gestire direttamente l'evento.

Esempio:

  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 */ }
  }

• Aggiungi la proprietà progress a NavigationEventState (I7b196) che restituisce latestEvent.progress quando è in corso o 0F in caso contrario:

  val progress = state.progress
  

• Aggiungi il composable NavigationEventDispatcherOwner per creare, collegare ed eliminare le istanze NavigationEventDispatcher in modo gerarchico. Consente il controllo dinamico dello stato abilitato del dispatcher e la pulizia automatica.

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

Modifiche alle API

• Il parametro isPassthrough è stato rimosso da NavigationEventCallback. (I99028, b/424470518)
• I costruttori NavigationEventState sono ora interni. Per i test, aggiorna lo stato (il valore predefinito è Idle) tramite DirectNavigationEventInputHandler. Chiama handleOnStarted o handleOnProgressed per impostare lo stato su InProgress e handleOnCompleted o handleOnCancelled per riportarlo a Idle. Per aggiornare NavigationEventInfo, utilizza NavigationEventCallback.setInfo. (I93dca, b/424470518)
• Sono stati aggiunti parametri predefiniti a NavigationEvent per consentire un'istanza più semplice e semplificare i test, che devono essere utilizzati al posto di TestNavigationEvent. (I5dc49, I232f4)
• È stato aggiunto un TestNavigationEventCallback per testare gli eventi di navigazione con stati attuali/precedenti specifici. (Idd22e, b/424470518)
• NavigationEventInputHandler è stata trasformata in una classe astratta per sostituire la precedente AbstractNavigationEventInputHandler con un'implementazione in DirectNavigationEventInputHandler (Iadde5, Ifed40I3897c, b/432616296, b/435416924)
• I prefissi delle funzioni send* in NavigationEventInputHandler sono stati rinominati in handle*. (Iffcaf)
• OnBackInvokedInputHandler ora estende il nuovo abstract NavigationInputHandler. (Ib45aa)
• È stato modificato NavigationEventDispatcherOwner in modo da richiedere un dispatcher principale in cui devi passare esplicitamente null per creare un dispatcher radice. (Ia6f64, b/431534103)

Correzioni di bug

• Maggiore efficienza evitando le copie delle raccolte in NavigationEventDispatcher.dispose(). (I4ab09)
• Risolto un problema per cui NavigationEventHandler non rispondeva correttamente alle modifiche del suo stato di attivazione. (Ia5268,I19bec, I5be5c, b/431534103)

Aggiornamenti di Documenti

• KDocs per NavigationEvent è stato ampliato per chiarire il suo ruolo di wrapper di eventi unificato e il comportamento dettagliato delle proprietà nei diversi tipi di navigazione (gesti, clic). (I91e8d)
• È stata aggiornata la documentazione per la gestione del pulsante Indietro del sistema delle API Compose (BackHandler, PredictiveBackHandler, NavigationEventHandler) per descrivere il comportamento specifico relativo all'ordine di callback. (I7ab94, )

Aggiornamento delle dipendenze

• NavigationEvent ora dipende da Compose Runtime 1.9.0-beta03, che consente all'artefatto navigationevent-compose di supportare tutti i target KMP. (Ia1b87)

Versione 1.0.0-alpha05

30 luglio 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha05 viene rilasciata. 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 elemento 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 rilasciata. 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 rilasciata. 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 rilasciata. 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 rilasciata. 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.