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
30 de julio de 2025 - - - 1.0.0-alpha05

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-alpha05"
}

Kotlin

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

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