navigationevent

  
La bibliothèque Navigation Event fournit une API KMP-first pour gérer le retour système ainsi que la prévisualisation du Retour.
Dernière mise à jour Version stable Version finale Version bêta Version alpha
30 juillet 2025 - - - 1.0.0-alpha05

Déclarer des dépendances

Pour ajouter une dépendance à navigationevent, vous devez ajouter le dépôt Maven de Google à votre projet. Pour en savoir plus, consultez la section Dépôt Maven de Google.

Ajoutez les dépendances correspondant aux artefacts dont vous avez besoin dans le fichier build.gradle de votre application ou de votre module :

Groovy

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

Kotlin

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

Pour en savoir plus sur les dépendances, consultez Ajouter des dépendances de compilation.

Commentaires

Vos commentaires nous aident à améliorer Jetpack. N'hésitez pas à nous contacter si vous découvrez de nouveaux problèmes ou si vous avez des idées pour améliorer cette bibliothèque. Veuillez consulter les problèmes existants de cette bibliothèque avant d'en signaler un nouveau. Vous pouvez ajouter votre vote à un problème existant en cliquant sur le bouton en forme d'étoile.

Signaler un nouveau problème

Pour en savoir plus, consultez la documentation sur l'outil Issue Tracker.

Aucune note de version pour cet artefact.

Version 1.0

Version 1.0.0-alpha05

30 juillet 2025

Publication d'androidx.navigationevent:navigationevent-*:1.0.0-alpha05. La version 1.0.0-alpha05 contient ces commits.

Prise en charge de la hiérarchie parent-enfant :

Un NavigationEventDispatcher peut désormais avoir des dispatchers parents et enfants, formant une structure arborescente hiérarchique. Cela permet aux événements de navigation de se propager et d'être gérés de manière plus flexible dans les composants d'interface utilisateur Compose complexes en reflétant la hiérarchie structurelle de l'UI via des dispatchers chaînés. (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 propriété hiérarchique isEnabled permet un contrôle descendant d'un répartiteur. Lorsque isEnabled est défini sur false sur un répartiteur, tous ses répartiteurs descendants sont automatiquement désactivés. Cette fonctionnalité permet de désactiver efficacement des branches entières du système d'événements de navigation. (I9e985)

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

De plus, la propriété isEnabled sur NavigationEventCallback respecte désormais l'état activé de son répartiteur associé. Cela signifie qu'un rappel n'est considéré comme activé que si le rappel lui-même et son répartiteur (y compris ses ancêtres) sont activés. Cela garantit un contrôle hiérarchique cohérent sur l'activation des rappels. (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()

Une nouvelle méthode dispose() a été introduite pour nettoyer correctement les dispatchers et leurs enfants. L'appel de dispose() arrête les écouteurs pour éviter les fuites de mémoire, supprime de manière récursive tous les dispatchers enfants, supprime tous les rappels enregistrés auprès du dispatcher et le dissocie de son parent. Cela garantit que les ressources sont libérées correctement lorsque les dispatchers ne sont plus nécessaires. (I9e985)

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

Si une méthode publique est appelée sur un répartiteur supprimé, une IllegalStateException est immédiatement générée. Cela permet d'éviter les échecs silencieux et aide les développeurs à identifier les utilisations incorrectes pendant le développement. (Ic2dc3)

  val callback2 = TestNavigationEventCallback()

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

Remarque : Nous allons introduire un nouveau composable NavigationEventDispatcherOwner qui gère automatiquement un répartiteur enfant dans l'UI Compose dans aosp/3692572. Toutefois, ce changement n'a pas été inclus dans la version actuelle et est prévu pour la prochaine.

Bibliothèque de test de navigation

  • Ajoutez le module navigationevent-testing pour fournir des utilitaires de test dédiés à la bibliothèque navigationevent. (0e50b6)
  • Ajout de la classe utilitaire fictive TestNavigationEventCallback pour les tests. Il enregistre les appels de méthode de rappel et stocke les éléments NavigationEvent reçus pour faciliter la validation. (4a0246)
  • Ajout d'une fonction utilitaire factice TestNavigationEvent pour créer des instances NavigationEvent avec des valeurs par défaut, ce qui simplifie les tests unitaires pour le traitement des événements de navigation. (3b63f5)
  • Ajout de la classe utilitaire fictive TestNavigationEventDispatcherOwner pour les tests. Il suit le nombre d'événements de changement d'état (activé/désactivé) et de secours pour permettre la vérification des interactions dans les tests. (c8753e)

Modifications apportées à l'API

  • Déplacez NavigationEventInputHandler de androidMain vers commonMain pour le rendre disponible dans le code commun KMP. Ajout de nouvelles méthodes public send* pour distribuer les événements. Modifiez les fonctions de répartition sur NavigationEventDispatcher de public à internal. Les utilisateurs doivent désormais utiliser NavigationEventInputHandler pour envoyer des événements. (Ia7114)
  • NavigationInputHandler a été renommé OnBackInvokedInputHandler. (I63405)

Correction de bugs

  • Refactorisez NavigationEventDispatcher pour réduire la surcharge en évitant les allocations de listes intermédiaires et en améliorant les performances de répartition des rappels. (I82702, I1a9d9)
  • Ajout d'annotations @FloatRange aux champs touchX, touchY et progress dans NavigationEvent pour appliquer des plages de valeurs valides au moment de la compilation et améliorer la sécurité de l'API. (Iac0ec)

Version 1.0.0-alpha04

2 juillet 2025

Publication d'androidx.navigationevent:navigationevent-*:1.0.0-alpha04. La version 1.0.0-alpha04 contient ces commits.

Correction de bugs

  • Utilisation de implementedInJetBrainsFork pour navigationevent-compose et ajout d'une cible commonStubs pour correspondre aux conventions Compose. Modification demandée par JetBrains. (f60c79)
  • Correction de l'application du plug-in de compilation Compose pour Kotlin/Native afin de garantir la génération correcte des stubs. Aucune incidence sur les API ni le comportement publics. (1890c9)

Version 1.0.0-alpha03

18 juin 2025

Publication d'androidx.navigationevent:navigationevent-*:1.0.0-alpha03. La version 1.0.0-alpha03 contient ces commits.

Nouvelles fonctionnalités

  • Ajout d'un nouveau module navigationevent-compose pour prendre en charge les fonctionnalités Jetpack Compose dans la bibliothèque navigationevent. (980d78)
  • NavigationEvent Compose a ajouté une nouvelle composition locale LocalNavigationEventDispatcherOwner. Elle renvoie une possibilité de valeur nulle pour mieux déterminer si elle est disponible dans la composition actuelle. NavigationEventHandler génère désormais une erreur si le propriétaire associé est introuvable. (62ffda)
  • NavigationEvent Compose a ajouté un nouveau composable NavigationEventHandler pour gérer les événements (prévisualisation du geste Retour). Il fournit un Flow d'objets NavigationEvent qui doivent être collectés dans le lambda de suspension que vous fournissez 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
  }
}

Modifications apportées à l'API

  • Chaque NavigationEventCallback ne peut désormais être enregistré qu'auprès d'un seul NavigationEventDispatcher à la fois. Si vous l'ajoutez à plusieurs dispatchers, une erreur IllegalStateException se produit. Notez que ce comportement diffère de OnBackPressedDispatcher, qui autorise plusieurs coordinateurs. (e82c19)
  • isPassThrough est désormais un val pour éviter toute mutation pendant la navigation, ce qui pourrait interrompre l'envoi de NavigationEvent. (I0b287)

Version 1.0.0-alpha02

4 juin 2025

Publication d'androidx.navigationevent:navigationevent-*:1.0.0-alpha02. La version 1.0.0-alpha02 contient ces commits.

Modifications apportées à l'API

  • Remplacez le constructeur secondaire de NavigationEventDispatcher par des arguments par défaut. (I716a0)
  • Supprimez la propriété de priorité de NavigationEventCallback. Transmettez plutôt la priorité à NavigationEventDispatcher.addCallback(). (I13cae)

Correction de bugs

  • Correction d'une ConcurrentModificationException qui pouvait se produire lors de l'appel de NavigationEventCallback.remove() en raison de la modification simultanée de la liste interne des éléments fermables. (b/420919815)

Version 1.0.0-alpha01

20 mai 2025

Publication d'androidx.navigationevent:navigationevent-*:1.0.0-alpha01. La version 1.0.0-alpha01 contient ces commits.

Nouvelles fonctionnalités

  • La bibliothèque androidx.navigationevent fournit une API KMP-first pour gérer le retour système ainsi que la prévisualisation du Retour. NavigationEventDispatcher sert d'API commune pour enregistrer une ou plusieurs instances NavigationEventCallback afin de recevoir les événements de retour système.
  • Cette couche se situe en dessous des API publiées précédemment dans androidx.activity et vise à remplacer de manière moins arbitraire l'utilisation des API Activity dans les composants de niveau supérieur ou l'utilisation directe des API OnBackInvokedDispatcher du framework Android. Les API androidx.activity ont été réécrites au-dessus des API Navigation Event dans le cadre d'Activity 1.12.0-alpha01.