navigationevent

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 :

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

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

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

13 août 2025

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

Nouvelles fonctionnalités

API Passive Listeners

Vous pouvez désormais transmettre des informations contextuelles personnalisées depuis n'importe quel hôte de navigation et écouter passivement les changements d'état des gestes depuis n'importe quel endroit de votre UI. Cela permet d'activer des animations contextuelles pour la prévisualisation du geste Retour et d'autres types de navigation par gestes.

Cette fonctionnalité comporte deux volets :

1. Fournir des informations : utilisez NavigationEventInfo pour transmettre des données personnalisées.
2. État de consommation : utilisez dispatcher.state (NavigationEventState) pour observer la progression et le contexte du geste.

• NavigationEventCallback expose désormais la méthode setInfo(currentInfo, previousInfo) pour définir le contexte du geste en un seul appel (I1d5e7, b/424470518).
• NavigationEventHandler ajoute une nouvelle surcharge qui accepte currentInfo et previousInfo, ce qui en fait l'API principale pour fournir le contexte dans les applications Compose (I6ecd3, b/424470518).

Exemple :

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

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

• NavigationEventDispatcher expose désormais dispatcher.state et dispatcher.getState<T>() (If7fae, Ia90ca, b/424470518). Ces API basées sur StateFlow permettent à n'importe quelle UI d'observer la progression des gestes et les données contextuelles sans gérer directement l'événement.

Exemple :

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

• Ajoutez la propriété progress à NavigationEventState (I7b196) qui renvoie latestEvent.progress en cas de progression ou 0F dans le cas contraire :

  val progress = state.progress
  

• Ajout du composable NavigationEventDispatcherOwner pour créer, associer et supprimer des instances NavigationEventDispatcher de manière hiérarchique. Activez le contrôle dynamique de l'état activé du répartiteur et le nettoyage automatique.

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

Modifications apportées à l'API

• Le paramètre isPassthrough a été supprimé de NavigationEventCallback. (I99028, b/424470518)
• Les constructeurs NavigationEventState sont désormais internes. Pour les tests, mettez à jour l'état (par défaut, Idle) via DirectNavigationEventInputHandler. Appelez handleOnStarted ou handleOnProgressed pour définir l'état sur InProgress, et handleOnCompleted ou handleOnCancelled pour le rétablir sur Idle. Pour mettre à jour NavigationEventInfo, utilisez NavigationEventCallback.setInfo. (I93dca, b/424470518)
• Ajout de paramètres par défaut à NavigationEvent pour faciliter l'instanciation et simplifier les tests, qui doivent être utilisés à la place de TestNavigationEvent. (I5dc49, I232f4)
• Ajout d'un TestNavigationEventCallback pour tester les événements de navigation avec des états actuels/précédents spécifiques. (Idd22e, b/424470518)
• NavigationEventInputHandler est désormais une classe abstraite qui remplace l'ancienne AbstractNavigationEventInputHandler par une implémentation dans DirectNavigationEventInputHandler. (Iadde5, Ifed40I3897c, b/432616296, b/435416924)
• Le préfixe des fonctions send* dans NavigationEventInputHandler a été remplacé par handle*. (Iffcaf)
• OnBackInvokedInputHandler étend désormais le nouveau NavigationInputHandler abstract. (Ib45aa)
• Modification de NavigationEventDispatcherOwner pour exiger un répartiteur parent où vous devez transmettre explicitement null pour créer un répartiteur racine. (Ia6f64, b/431534103)

Correction de bugs

• Efficacité améliorée en évitant les copies de collections dans NavigationEventDispatcher.dispose(). (I4ab09)
• Correction d'un problème où NavigationEventHandler ne répondait pas correctement aux modifications de son état activé. (Ia5268,I19bec, I5be5c, b/431534103)

Nouveautés de Docs

• La documentation KDocs pour NavigationEvent a été étendue pour clarifier son rôle d'encapsuleur d'événements unifié et détailler le comportement des propriétés pour différents types de navigation (gestes, clics). (I91e8d)
• Mise à jour de la documentation pour les API Compose de gestion du retour système (BackHandler, PredictiveBackHandler, NavigationEventHandler) afin de préciser le comportement, en particulier en ce qui concerne l'ordre des rappels. (I7ab94, )

Mise à jour de la dépendance

• NavigationEvent dépend désormais de Compose Runtime 1.9.0-beta03, ce qui permet à l'artefact navigationevent-compose de prendre en charge toutes les cibles KMP. (Ia1b87)

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.