navigationevent

  
La biblioteca de Navigation Event proporciona una API que prioriza KMP para controlar el botón Atrás del sistema y el Atrás predictivo.
Actualización más reciente Versión estable Versión potencial Versión beta Versión alfa
13 de agosto de 2025 - - - 1.0.0-alpha06

Cómo declarar dependencias

Para agregar una dependencia en navigationevent, debes agregar el repositorio de Maven de Google a tu proyecto. Consulta el repositorio de Maven de Google para obtener más información.

Agrega las dependencias de los artefactos que necesites en el archivo build.gradle de tu app o módulo:

Groovy

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

Kotlin

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

Para obtener más información sobre las dependencias, consulta Cómo agregar dependencias de compilación.

Comentarios

Tus comentarios ayudan a mejorar Jetpack. Avísanos si descubres nuevos errores o tienes ideas para mejorar esta biblioteca. Consulta los errores existentes de esta biblioteca antes de crear uno nuevo. Puedes agregar tu voto a un error existente haciendo clic en el botón de la estrella.

Crear un error nuevo

Consulta la documentación sobre la Herramienta de seguimiento de errores para obtener más información.

No hay notas de la versión para este artefacto.

Versión 1.0

Versión 1.0.0-alpha06

13 de agosto de 2025

Lanzamiento de androidx.navigationevent:navigationevent-*:1.0.0-alpha06. La versión 1.0.0-alpha06 contiene estas confirmaciones.

Nuevas funciones

API de Passive Listeners

Ahora puedes pasar información contextual personalizada desde cualquier host de navegación y escuchar de forma pasiva los cambios de estado de los gestos desde cualquier lugar de tu IU. Esto habilita animaciones contextuales para el gesto atrás predictivo y otros tipos de navegación controlados por gestos.

Esta función tiene dos partes:

  1. Providing Info: Usa NavigationEventInfo para transportar datos personalizados.
  2. Estado de consumo: Usa dispatcher.state (NavigationEventState) para observar el progreso y el contexto del gesto.
  • NavigationEventCallback ahora expone el método setInfo(currentInfo, previousInfo) para establecer el contexto de gestos en una sola llamada (I1d5e7, b/424470518).
  • NavigationEventHandler agrega una nueva sobrecarga que acepta currentInfo y previousInfo, lo que la convierte en la API principal para proporcionar contexto en las apps de Compose (I6ecd3, b/424470518).

Ejemplo:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • NavigationEventDispatcher ahora expone dispatcher.state y dispatcher.getState<T>() (If7fae, Ia90ca, b/424470518). Estas APIs basadas en StateFlow permiten que cualquier IU observe el progreso del gesto y los datos contextuales sin controlar el evento directamente.

Ejemplo:

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

  • Agrega la propiedad progress a NavigationEventState (I7b196) que devuelve latestEvent.progress cuando está en curso o 0F en otros casos:

    val progress = state.progress

  • Se agregó el elemento NavigationEventDispatcherOwner componible para crear, vincular y desechar instancias de NavigationEventDispatcher de forma jerárquica. Permite el control dinámico del estado habilitado del despachador y la limpieza automática.

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

Cambios en la API

  • Se quitó el parámetro isPassthrough de NavigationEventCallback. (I99028, b/424470518)
  • Ahora, los constructores de NavigationEventState son internos. Para realizar pruebas, actualiza el estado (el valor predeterminado es Idle) a través de DirectNavigationEventInputHandler. Llama a handleOnStarted o handleOnProgressed para establecer el estado en InProgress, y a handleOnCompleted o handleOnCancelled para volver a Idle. Para actualizar NavigationEventInfo, usa NavigationEventCallback.setInfo. (I93dca, b/424470518)
  • Se agregaron parámetros predeterminados a NavigationEvent para permitir una instanciación más sencilla y simplificar las pruebas que se deben usar en lugar de TestNavigationEvent. (I5dc49, I232f4)
  • Se agregó un TestNavigationEventCallback para probar eventos de navegación con estados actuales o anteriores específicos. (Idd22e, b/424470518)
  • NavigationEventInputHandler se convirtió en una clase abstracta para reemplazar el AbstractNavigationEventInputHandler anterior por una implementación en DirectNavigationEventInputHandler (Iadde5, Ifed40I3897c, b/432616296, b/435416924).
  • Se cambió el nombre de los prefijos de las funciones send* en NavigationEventInputHandler por handle*. (Iffcaf)
  • Ahora, OnBackInvokedInputHandler extiende el nuevo abstract NavigationInputHandler. (Ib45aa)
  • Se cambió NavigationEventDispatcherOwner para que requiera un distribuidor principal en el que debes pasar null de forma explícita para crear un distribuidor raíz. (Ia6f64, b/431534103)

Correcciones de errores

  • Se mejoró la eficiencia evitando copias de recopilación en NavigationEventDispatcher.dispose(). (I4ab09)
  • Se corrigió un problema por el que NavigationEventHandler no respondía correctamente a los cambios en su estado habilitado. (Ia5268,I19bec, I5be5c, b/431534103)

Actualizaciones de la documentación

  • Se expandieron los KDocs para NavigationEvent para aclarar su rol como wrapper de eventos unificado y el comportamiento de las propiedades de detalle en diferentes tipos de navegación (gestos, clics). (I91e8d)
  • Se actualizó la documentación para el control del sistema hacia atrás de las APIs de Compose (BackHandler, PredictiveBackHandler, NavigationEventHandler) para destacar el comportamiento específicamente en torno al orden de devolución de llamada. (I7ab94, )

Actualización de dependencia

  • NavigationEvent ahora depende de Compose Runtime 1.9.0-beta03, lo que permite que el artefacto navigationevent-compose admita todos los destinos de KMP. (Ia1b87)

Versión 1.0.0-alpha05

30 de julio de 2025

Lanzamiento de androidx.navigationevent:navigationevent-*:1.0.0-alpha05. La versión 1.0.0-alpha05 contiene estas confirmaciones.

Compatibilidad con la jerarquía superior-secundario:

Un NavigationEventDispatcher ahora puede tener despachadores principales y secundarios, lo que forma una estructura de árbol jerárquica. Esto permite que los eventos de navegación se propaguen y se administren de manera más flexible en los componentes de IU de Compose complejos, ya que reflejan la jerarquía estructural de la IU a través de distribuidores encadenados. (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 propiedad jerárquica isEnabled permite el control descendente de un dispatcher. Cuando isEnabled se establece en false en un dispatcher, se inhabilitan automáticamente todos sus dispatchers descendientes. Esta función permite desactivar ramas completas del sistema de eventos de navegación de manera eficiente. (I9e985)

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

Además, la propiedad isEnabled en NavigationEventCallback ahora respeta el estado habilitado de su dispatcher asociado. Esto significa que una devolución de llamada se considera habilitada solo si la devolución de llamada en sí y su dispatcher (incluidos sus elementos superiores) están habilitados, lo que garantiza un control jerárquico coherente sobre la activación de la devolución de llamada. (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()

Se introdujo un nuevo método dispose() para limpiar correctamente los despachadores y sus elementos secundarios. Si llamas a dispose(), se detienen los objetos de escucha para evitar fugas de memoria, se descartan de forma recursiva todos los distribuidores secundarios, se quitan todas las devoluciones de llamada registradas en el distribuidor y se desvincula del elemento superior. Esto garantiza que los recursos se liberen correctamente cuando ya no se necesiten los despachadores. (I9e985)

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

Si se llama a algún método público en un dispatcher descartado, se arroja un IllegalStateException de inmediato. Esto evita errores silenciosos y ayuda a los desarrolladores a identificar el uso inadecuado durante el desarrollo. (Ic2dc3)

  val callback2 = TestNavigationEventCallback()

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

Nota: Presentaremos un nuevo elemento NavigationEventDispatcherOwner Composable que administra automáticamente un dispatcher secundario dentro de la IU de Compose en aosp/3692572. Sin embargo, este cambio no se incluyó en la versión actual y se planea para la próxima.

Biblioteca de pruebas de navegación

  • Se agregó el módulo navigationevent-testing para proporcionar utilidades de prueba dedicadas para la biblioteca de navigationevent. (0e50b6)
  • Se agregó la clase de utilidad falsa TestNavigationEventCallback para las pruebas. Registra las llamadas a métodos de devolución de llamada y almacena los elementos NavigationEvent recibidos para admitir la verificación. (4a0246)
  • Se agregó la función de utilidad falsa TestNavigationEvent para crear instancias de NavigationEvent con valores predeterminados, lo que simplifica las pruebas de unidades para el procesamiento de eventos de navegación. (3b63f5)
  • Se agregó la clase de utilidad falsa TestNavigationEventDispatcherOwner para las pruebas. Realiza un seguimiento de los recuentos de eventos de cambio de estado habilitado y de resguardo para admitir la verificación de interacciones en las pruebas. (c8753e)

Cambios en la API

  • Mueve NavigationEventInputHandler de androidMain a commonMain para que esté disponible en el código común de KMP. Se agregaron nuevos métodos public send* para despachar eventos. Cambia las funciones de envío en NavigationEventDispatcher de public a internal; ahora los usuarios deben usar NavigationEventInputHandler para enviar eventos. (Ia7114)
  • Se cambió el nombre de NavigationInputHandler por OnBackInvokedInputHandler. (I63405)

Correcciones de errores

  • Se refactorizó NavigationEventDispatcher para reducir la sobrecarga evitando las asignaciones de listas intermedias y mejorando el rendimiento del envío de devoluciones de llamada. (I82702, I1a9d9)
  • Se agregaron anotaciones @FloatRange a los campos touchX, touchY y progress en NavigationEvent para aplicar rangos de valores válidos en el tiempo de compilación y mejorar la seguridad de la API. (Iac0ec)

Versión 1.0.0-alpha04

2 de julio de 2025

Lanzamiento de androidx.navigationevent:navigationevent-*:1.0.0-alpha04. La versión 1.0.0-alpha04 contiene estas confirmaciones.

Correcciones de errores

  • Se usó implementedInJetBrainsFork para navigationevent-compose y se agregó un destino commonStubs para que coincida con las convenciones de Compose. Cambio solicitado por JetBrains. (f60c79)
  • Se corrigió la aplicación del complemento del compilador de Compose para Kotlin/Native para garantizar la generación correcta de stubs. No hay impacto en las APIs ni el comportamiento públicos. (1890c9)

Versión 1.0.0-alpha03

18 de junio de 2025

Lanzamiento de androidx.navigationevent:navigationevent-*:1.0.0-alpha03. La versión 1.0.0-alpha03 contiene estas confirmaciones.

Nuevas funciones

  • Se introdujo un nuevo módulo navigationevent-compose para admitir funciones de Jetpack Compose en la biblioteca navigationevent. (980d78)
  • NavigationEvent Compose agregó una nueva composición local LocalNavigationEventDispatcherOwner. Devuelve un valor anulable para determinar mejor si está disponible en la composición actual. NavigationEventHandler ahora generará un error si no se encuentra el propietario subyacente. (62ffda)
  • NavigationEvent Compose agregó un nuevo elemento NavigationEventHandler componible para controlar eventos (gesto atrás predictivo). Proporciona un Flow de objetos NavigationEvent que se deben recopilar en la expresión lambda de suspensión que proporcionas 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
  }
}

Cambios en la API

  • Ahora, cada NavigationEventCallback solo se puede registrar con un NavigationEventDispatcher a la vez. Si se agrega a varios despachadores, se arroja un IllegalStateException. Ten en cuenta que este comportamiento difiere de OnBackPressedDispatcher, que permite varios despachadores. (e82c19)
  • Se convirtió isPassThrough en val para evitar la mutación durante la navegación, lo que podría interrumpir el envío de NavigationEvent. (I0b287)

Versión 1.0.0-alpha02

4 de junio de 2025

Lanzamiento de androidx.navigationevent:navigationevent-*:1.0.0-alpha02. La versión 1.0.0-alpha02 contiene estas confirmaciones.

Cambios en la API

  • Reemplaza el constructor secundario de NavigationEventDispatcher por argumentos predeterminados. (I716a0)
  • Quita la propiedad de prioridad de NavigationEventCallback. En su lugar, pasa la prioridad a NavigationEventDispatcher.addCallback(). (I13cae)

Correcciones de errores

  • Se corrigió un ConcurrentModificationException que podía ocurrir cuando se llamaba a NavigationEventCallback.remove() debido a la modificación simultánea de la lista interna de elementos que se pueden cerrar. (b/420919815)

Versión 1.0.0-alpha01

20 de mayo de 2025

Lanzamiento de androidx.navigationevent:navigationevent-*:1.0.0-alpha01. La versión 1.0.0-alpha01 contiene estas confirmaciones.

Nuevas funciones

  • La biblioteca de androidx.navigationevent proporciona una API que prioriza KMP para controlar el sistema hacia atrás, así como Atrás predictivo. El elemento NavigationEventDispatcher funciona como una API común para registrar una o más instancias de NavigationEventCallback para recibir eventos de Atrás del sistema.
  • Esta capa se encuentra debajo de las APIs lanzadas anteriormente en androidx.activity y tiene como objetivo ser un reemplazo menos subjetivo para usar las APIs de Activity en componentes de nivel superior o usar directamente las APIs de OnBackInvokedDispatcher del framework de Android. Las APIs de androidx.activity se reescribieron sobre las APIs de Navigation Event como parte de Activity 1.12.0-alpha01.