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

La mise en page "Liste/Détail" est un modèle d'UI qui consiste en une mise en page à deux volets, l'un présentant une liste d'éléments et l'autre affichant 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 liste-détail peut également être utilisée pour des chemins moins critiques, par exemple pour diviser les préférences de l'application en une liste de catégories avec les préférences de chaque catégorie dans le volet d'informations.

Implémenter un modèle d'interface utilisateur avec ListDetailPaneScaffold

ListDetailPaneScaffold est un composable qui simplifie l'implémentation du modèle de liste/détail dans votre application. Un échafaudage de liste/détail peut comporter jusqu'à trois volets: un volet de liste, un volet d'informations et un volet supplémentaire facultatif. L'échafaudage gère les calculs de l'espace à l'écran. Lorsque la taille d'écran est suffisante, le volet d'informations s'affiche à côté du volet de liste. Sur les petits écrans, l'échafaudage affiche automatiquement le volet de liste ou de détails en plein écran.

Figure 1. Lorsque la taille d'écran est suffisante, le volet d'informations s'affiche à côté du volet de liste.

Figure 2. Lorsque la taille de l'écran est limitée, le volet d'informations (puisqu'un élément a été sélectionné) occupe tout l'espace.

Déclarer des dépendances

ListDetailPaneScaffold fait partie de la bibliothèque de mise en page 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'

• adaptative : éléments de base 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

Utilisation de base

Implémentez ListDetailPaneScaffold comme suit:

1. Utilisez une classe qui représente le contenu à sélectionner. Cette classe doit être 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.

   @Parcelize
   class MyItem(val id: Int) : Parcelable
   SampleListDetailPaneScaffold.kt

2. Créez un ThreePaneScaffoldNavigator avec rememberListDetailPaneScaffoldNavigator et ajoutez un BackHandler. 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 parcellable, l'état peut être enregistré et restauré par le navigateur pour gérer automatiquement les modifications de configuration. BackHandler permet de revenir en arrière à l'aide du geste ou du bouton de retour du système. Le comportement attendu du bouton "Retour" pour un ListDetailPaneScaffold dépend de la taille de la fenêtre et de la valeur actuelle de l'échafaudage. Si ListDetailPaneScaffold peut revenir à l'état actuel, canNavigateBack() est true, ce qui active BackHandler.

   val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
   
   BackHandler(navigator.canNavigateBack()) {
       navigator.navigateBack()
   }
   SampleListDetailPaneScaffold.kt

3. Transmettez scaffoldState de navigator au composable ListDetailPaneScaffold.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       // ...
   )
   SampleListDetailPaneScaffold.kt

4. Fournissez l'implémentation de votre volet de liste à ListDetailPaneScaffold. 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.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane = {
           AnimatedPane {
               MyList(
                   onItemClick = { item ->
                       // Navigate to the detail pane with the passed item
                       navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item)
                   }
               )
           }
       },
       // ...
   )
   SampleListDetailPaneScaffold.kt

5. Incluez l'implémentation de votre volet d'informations dans ListDetailPaneScaffold. 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é content est du même type que celui spécifié dans l'appel de mémorisation d'origine (MyItem dans cet exemple). Vous pouvez donc également accéder à la propriété pour toutes les données que vous devez afficher.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane =
       // ...
       detailPane = {
           AnimatedPane {
               navigator.currentDestination?.content?.let {
                   MyDetails(it)
               }
           }
       },
   )
   SampleListDetailPaneScaffold.kt

Une fois les étapes ci-dessus implémentées, votre code devrait se présenter comme suit:

val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

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