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

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

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'

• adaptive: composants de bas niveau tels que HingeInfo et Posture
• adaptive-layout: mises en page adaptatives telles que ListDetailPaneScaffold et SupportingPaneScaffold
• adaptive-navigation: composables permettant de naviguer dans et entre les volets, ainsi que des mises en page adaptatives compatibles avec la navigation par défaut, telles que NavigableListDetailPaneScaffold et NavigableSupportingPaneScaffold

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

Activer la prévisualisation du geste Retour

Pour activer les animations de prévisualisation du Retour sous Android 15 ou version antérieure, vous devez activer la prise en charge du geste Retour prévisualisé. Pour l'activer, 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 de la liste, des détails et des volets supplémentaires. En déclarant un type générique, le navigateur suit également l'état de l'échafaudage (c'est-à-dire quel MyItem est affiché). Étant donné que 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 de votre volet de liste à NavigableListDetailPaneScaffold. Utilisez AnimatedPane pour appliquer les animations de volet par défaut lors de 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'informations 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 ainsi accéder à toutes les données que vous devez afficher.

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

Si votre application nécessite un modèle de navigation "Retour" différent, vous pouvez ignorer 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.

PopUntilScaffoldValueChange (valeur par défaut et recommandée dans la plupart des cas)

Ce comportement se concentre sur les modifications apportées à la structure de mise en page globale. Dans une configuration multi-volets, modifier le contenu de l'e-mail dans le volet d'informations détaillées ne modifie pas la structure de mise en page sous-jacente. Par conséquent, le bouton "Retour" peut quitter l'application ou le graphe de navigation actuel, car il n'y a pas de modification de mise en page à laquelle revenir dans le contexte actuel. Dans une mise en page à un seul volet, appuyer sur "Retour" ignore les modifications de contenu dans la vue détaillée et revient à la vue Liste, car il s'agit d'un changement de mise en page clair.

Exemples :

• Multi-fenêtre:vous consultez un e-mail (élément 1) dans le volet d'informations. Si vous cliquez sur un autre e-mail (élément 2), le volet d'informations est mis à jour, mais les volets de liste et de détails restent visibles. Appuyer sur le bouton Retour peut entraîner la fermeture de l'application ou du parcours de navigation actuel.
• Volet unique:vous consultez l'élément 1, puis l'élément 2. Si vous appuyez sur "Retour", vous êtes redirigé directement vers le volet de la liste de diffusion.

Utilisez-le lorsque vous souhaitez que les utilisateurs perçoivent des transitions de mise en page distinctes à chaque action "Retour".

PopUntilContentChange

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

Exemples :

• Multi-fenêtre:vous affichez l'élément 1 dans le volet d'informations, puis cliquez sur l'élément 2 dans la liste. Le volet d'informations est mis à jour. Si vous appuyez sur "Retour", le volet d'informations revient à l'élément 1.
• Single-Pane (Panneau unique) : la même inversion de contenu se produit.

Utilisez-le lorsque votre utilisateur s'attend à revenir au contenu précédemment consulté avec l'action "Retour".

PopUntilCurrentDestinationChange

Ce comportement fait apparaître la pile "Retour" jusqu'à ce que la destination de navigation actuelle change. Cela s'applique également aux mises en page à un ou plusieurs panneaux.

Exemples :

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

Utilisez-le lorsque la navigation actuelle doit être clairement indiquée pour l'expérience utilisateur.

PopLatest

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

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

val scaffoldNavigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
val scope = rememberCoroutineScope()

NavigableListDetailPaneScaffold(
    navigator = scaffoldNavigator,
    listPane = {
        AnimatedPane {
            MyList(
                onItemClick = { item ->
                    // Navigate to the detail pane with the passed item
                    scope.launch {
                        scaffoldNavigator.navigateTo(
                            ListDetailPaneScaffoldRole.Detail,
                            item
                        )
                    }
                },
            )
        }
    },
    detailPane = {
        AnimatedPane {
            // Show the detail pane content if selected item is available
            scaffoldNavigator.currentDestination?.contentKey?.let {
                MyDetails(it)
            }
        }
    },
)
SampleListDetailPaneScaffold.kt