Créer une mise en page liste/détails

La vue liste/détails est un modèle d'interface utilisateur qui consiste en une mise en page à deux volets, où l'un présente une liste d'éléments et l'autre affiche les détails des éléments sélectionnés dans la liste.

Ce modèle est particulièrement utile pour les applications qui fournissent des informations détaillées sur les éléments de grandes collections, par exemple un client de messagerie qui contient une liste d'e-mails et le contenu détaillé de chaque message. La vue liste/détails peut également être utilisée pour des parcours moins critiques, par exemple pour diviser les préférences de l'application en une liste de catégories, les préférences de chaque catégorie étant affichées dans le volet d'informations.

Un volet Détails affiché à côté de la page de liste.
Figure 1. Lorsque la taille de l'écran est suffisante, le volet de détails s'affiche à côté du volet de liste.
Une fois qu'un élément est sélectionné, le volet de vue détaillée s'affiche en plein écran.
Figure 2. Lorsque la taille de l'écran est limitée, le volet de vue détaillée (puisqu'un élément a été sélectionné) occupe tout l'espace.

Implémenter le schéma Liste/Détails avec NavigableListDetailPaneScaffold

NavigableListDetailPaneScaffold est un composable qui simplifie l'implémentation d'une mise en page liste-détail dans Jetpack Compose. Il encapsule ListDetailPaneScaffold et ajoute des animations de navigation et de prévisualisation du Retour intégrées.

Un échafaudage liste/détails accepte jusqu'à trois volets :

  1. Volet Liste : affiche une collection d'éléments.
  2. Volet de vue détaillée : affiche les détails d'un élément sélectionné.
  3. Volet supplémentaire (facultatif) : fournit un contexte supplémentaire si nécessaire.

L'échafaudage s'adapte en fonction de la taille de la fenêtre :

  • Dans les grandes fenêtres, les volets de liste et de vue détaillée s'affichent côte à côte.
  • Dans les petites fenêtres, un seul volet est visible à la fois, et l'affichage change à mesure que les utilisateurs naviguent.

Déclarer des dépendances

NavigableListDetailPaneScaffold fait partie de la bibliothèque de navigation adaptative Material 3.

Ajoutez les trois dépendances associées suivantes au fichier build.gradle de votre application ou module :

Kotlin

implementation("androidx.compose.material3.adaptive:adaptive")
implementation("androidx.compose.material3.adaptive:adaptive-layout")
implementation("androidx.compose.material3.adaptive:adaptive-navigation")

Groovy

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'
  • adaptive : composants de base de bas niveau tels que HingeInfo et Posture
  • adaptive-layout : mises en page adaptatives telles que ListDetailPaneScaffold et SupportingPaneScaffold
  • adaptive-navigation : composables pour naviguer dans et entre les volets, ainsi que des mises en page adaptatives qui acceptent la navigation par défaut, comme NavigableListDetailPaneScaffold et NavigableSupportingPaneScaffold

Assurez-vous que votre projet inclut compose-material3-adaptive version 1.1.0-beta1 ou ultérieure.

Activer la prévisualisation du geste Retour

Pour activer les animations de prévisualisation du Retour dans Android 15 ou version antérieure, vous devez activer la prise en charge de la prévisualisation du geste Retour. Pour activer cette option, ajoutez android:enableOnBackInvokedCallback="true" à la balise <application> ou à des balises <activity> individuelles dans votre fichier AndroidManifest.xml. Pour en savoir plus, consultez Activer la prévisualisation du geste Retour.

Une fois que votre application cible Android 16 (niveau d'API 36) ou une version ultérieure, la prévisualisation du Retour est activée par défaut.

Utilisation de base

Implémentez NavigableListDetailPaneScaffold comme suit :

  1. Utilisez une classe qui représente le contenu sélectionné. Utilisez une classe Parcelable pour permettre l'enregistrement et la restauration de l'élément de liste sélectionné. Utilisez le plug-in kotlin-parcelize pour générer le code à votre place.
  2. Créez un ThreePaneScaffoldNavigator avec rememberListDetailPaneScaffoldNavigator.

Ce navigateur permet de passer d'un volet à l'autre (liste, détails et volet supplémentaire). En déclarant un type générique, le navigateur suit également l'état de l'échafaudage (c'est-à-dire quel MyItem est affiché). Comme ce type est parcelable, l'état peut être enregistré et restauré par le navigateur pour gérer automatiquement les modifications de configuration.

  1. Transmettez le navigateur au composable NavigableListDetailPaneScaffold.

  2. Fournissez l'implémentation du volet de liste à NavigableListDetailPaneScaffold. Utilisez AnimatedPane pour appliquer les animations de volet par défaut pendant la navigation. Utilisez ensuite ThreePaneScaffoldNavigator pour accéder au volet d'informations, ListDetailPaneScaffoldRole.Detail, et afficher l'élément transmis.

  3. Incluez l'implémentation de votre volet Détails dans NavigableListDetailPaneScaffold.

Une fois la navigation terminée, currentDestination contient le volet vers lequel votre application a navigué, y compris le contenu affiché dans le volet. La propriété contentKey est du même type que celui spécifié dans l'appel d'origine. Vous pouvez donc accéder à toutes les données que vous devez afficher.

  1. Vous pouvez également modifier le defaultBackBehavior dans NavigableListDetailPaneScaffold. Par défaut, NavigableListDetailPaneScaffold utilise PopUntilScaffoldValueChange pour defaultBackBehavior.

Si votre application nécessite un autre modèle de retour en arrière, vous pouvez remplacer ce comportement en spécifiant une autre option BackNavigationBehavior.

Options BackNavigationBehavior

La section suivante utilise l'exemple d'une application de messagerie avec une liste d'e-mails dans un volet et une vue détaillée dans l'autre.

Ce comportement se concentre sur les modifications apportées à la structure globale de la mise en page. Dans une configuration à plusieurs volets, la modification du contenu de l'e-mail dans le volet détaillé ne modifie pas la structure de la mise en page sous-jacente. Par conséquent, le bouton Retour peut quitter l'application ou le graphique de navigation actuel, car il n'y a pas de modification de mise en page à annuler dans le contexte actuel. Dans une mise en page à un seul volet, appuyer sur le bouton Retour permet d'ignorer les modifications de contenu dans la vue détaillée et de revenir à la vue sous forme de liste, car cela représente un changement de mise en page clair.

Prenons les exemples suivants :

  • Multi-volet : vous consultez un e-mail (élément 1) dans le volet Détails. Si l'utilisateur clique sur un autre e-mail (élément 2), la vue détaillée est mise à jour, mais la liste et la vue détaillée restent visibles. Si vous appuyez sur "Retour", vous risquez de quitter l'application ou le flux de navigation actuel.
  • Volet unique : vous consultez l'élément 1, puis l'élément 2. En appuyant sur "Retour", vous revenez directement au volet de la liste des e-mails.

Utilisez cette option lorsque vous souhaitez que les utilisateurs perçoivent des transitions de mise en page distinctes à chaque action de retour.

Illustration montrant les changements de valeur de navigation dans différents volets de mise en page.
PopUntilContentChange

Ce comportement donne la priorité au contenu affiché. Si vous affichez l'élément 1, puis l'élément 2, appuyer sur le bouton Retour vous ramènera à l'élément 1, quelle que soit la mise en page.

Prenons les exemples suivants :

  • Volet multiple : vous affichez l'élément 1 dans le volet de détails, puis vous cliquez sur l'élément 2 dans la liste. Le volet Détails est mis à jour. Si vous appuyez sur le bouton Retour, le volet de vue détaillée de l'élément 1 est restauré.
  • Volet unique : le même rétablissement du contenu se produit.

Utilisez cette option lorsque l'utilisateur s'attend à revenir au contenu précédemment consulté avec l'action de retour.

la transition entre deux volets Détails
PopUntilCurrentDestinationChange

Ce comportement fait sortir la pile "Retour" jusqu'à ce que la destination de navigation actuelle change. Cela s'applique aussi bien aux mises en page à un seul volet qu'à celles à plusieurs volets.

Prenons les exemples suivants :

Que vous utilisiez une mise en page à un ou plusieurs volets, appuyer sur "Retour" déplace toujours le focus de l'élément de navigation mis en surbrillance vers la destination précédente. Dans notre application de messagerie, cela signifie que l'indication visuelle du volet sélectionné va changer.

Utilisez cette option lorsqu'il est essentiel de conserver une indication visuelle claire de la navigation actuelle pour l'expérience utilisateur.

naviguer entre les volets de détails et de liste
PopLatest

Cette option ne supprime que la destination la plus récente de la pile "Retour". Utilisez cette option pour revenir en arrière sans ignorer les états intermédiaires.

Une fois ces étapes terminées, votre code doit se présenter comme suit :

NavigableListDetailPaneScaffold(
    navigator = navigator,
    listPane = {
        AnimatedPane {
            ListContent(
                words = sampleWords,
                selectionState = navigator.currentDestination?.contentKey?.let {
                    SelectionVisibilityState.ShowSelection(it)
                } ?: SelectionVisibilityState.NoSelection,
                onWordClick = { word ->
                    scope.launch {
                        navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, word)
                    }
                },
                animatedVisibilityScope = this@AnimatedPane,
                sharedTransitionScope = this@SharedTransitionLayout
            )
        }
    },
    detailPane = {
        AnimatedPane {
            DetailContent(
                definedWord = navigator.currentDestination?.contentKey,
                animatedVisibilityScope = this@AnimatedPane,
                sharedTransitionScope = this@SharedTransitionLayout,
                onClosePane = {
                    scope.launch {
                        navigator.navigateBack(
                            backNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
                        )

                    }
                }
            )
        }
    }