Ein Listen-Detail-Layout erstellen

Das Listendetail ist ein UI-Muster, das aus einem zweispaltigen Layout besteht, in dem in einer Spalte eine Liste von Elementen und in einer anderen Spalte die Details der aus der Liste ausgewählten Elemente angezeigt werden.

Das Muster ist besonders nützlich für Anwendungen, die detaillierte Informationen zu Elementen großer Sammlungen enthalten, z. B. ein E-Mail-Client mit einer Liste von E-Mails und dem detaillierten Inhalt jeder E-Mail-Nachricht. Listendetails können auch für weniger kritische Pfade verwendet werden, z. B. um App-Einstellungen in eine Liste von Kategorien aufzuteilen, wobei die Einstellungen für jede Kategorie im Detailbereich angezeigt werden.

UI-Muster mit ListDetailPaneScaffold implementieren

ListDetailPaneScaffold ist eine zusammensetzbare Funktion, die die Implementierung des Listen-Detail-Musters in Ihrer App vereinfacht. Ein Listen-Detail-Gerüst kann aus bis zu drei Bereichen bestehen: einem Listen-, einem Detail- und einem optionalen zusätzlichen Bereich. Das Scaffold übernimmt die Berechnungen des Bildschirmbereichs. Wenn eine ausreichende Bildschirmgröße verfügbar ist, wird der Detailbereich neben dem Listenbereich angezeigt. Auf kleinen Bildschirmen wechselt das Scaffolding automatisch dazu, entweder die Liste oder den Detailbereich im Vollbildmodus anzuzeigen.

Abbildung 1: Wenn genügend Bildschirmgröße verfügbar ist, wird der Detailbereich neben dem Listenbereich angezeigt.

Abbildung 2. Wenn die Bildschirmgröße begrenzt ist, nimmt der Detailbereich (da ein Element ausgewählt wurde) den gesamten Bereich ein.

Abhängigkeiten deklarieren

ListDetailPaneScaffold gehört zur Bibliothek für adaptives Layout von Material 3.

Fügen Sie der build.gradle-Datei Ihrer App oder Ihres Moduls die folgenden drei zugehörigen Abhängigkeiten hinzu:

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: Low-Level-Bausteine wie HingeInfo und Posture
• adaptive-layout: Adaptive Layouts wie ListDetailPaneScaffold und SupportingPaneScaffold
• adaptive-navigation: Composeables für die Navigation innerhalb und zwischen Bereichen

Grundlegende Verwendung

Implementieren Sie ListDetailPaneScaffold so:

1. Verwenden Sie eine Klasse, die den auszuwählenden Inhalt darstellt. Diese Klasse sollte Parcelable sein, um das Speichern und Wiederherstellen des ausgewählten Listenelements zu unterstützen. Verwenden Sie das kotlin-parcelize-Plug-in, um den Code für Sie zu generieren.

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

2. Erstellen Sie eine ThreePaneScaffoldNavigator mit rememberListDetailPaneScaffoldNavigator und fügen Sie eine BackHandler hinzu. Mit diesem Navigationspfad können Sie zwischen der Liste, den Details und den zusätzlichen Bereichen wechseln. Durch die Deklarierung eines generischen Typs überwacht der Navigationspfad auch den Status des Scaffolds, d. h., welche MyItem angezeigt wird. Da dieser Typ teilbar ist, kann der Status vom Navigationssystem gespeichert und wiederhergestellt werden, um Konfigurationsänderungen automatisch zu verarbeiten. Mit BackHandler können Sie über die Systemgeste oder -schaltfläche zurückgehen. Das erwartete Verhalten der Schaltfläche „Zurück“ für eine ListDetailPaneScaffold hängt von der Fenstergröße und dem aktuellen Scaffold-Wert ab. Wenn ListDetailPaneScaffold die Rückkehr mit dem aktuellen Status unterstützen kann, hat canNavigateBack() den Wert true. Dadurch wird BackHandler aktiviert.

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

3. Übergeben Sie scaffoldState von navigator an die zusammensetzbare ListDetailPaneScaffold.

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

4. Stellen Sie Ihre Listenbereich-Implementierung für den ListDetailPaneScaffold bereit. Verwenden Sie AnimatedPane, um die Standardfensteranimationen während der Navigation anzuwenden. Gehen Sie dann mit ThreePaneScaffoldNavigator zum Detailbereich ListDetailPaneScaffoldRole.Detail und zeigen Sie das übergebene Element an.

   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. Fügen Sie die Implementierung des Detailbereichs in ListDetailPaneScaffold ein. Wenn die Navigation abgeschlossen ist, enthält currentDestination den Bereich, zu dem Ihre App gewechselt ist, einschließlich der darin angezeigten Inhalte. Die Property content hat denselben Typ wie im ursprünglichen remember-Aufruf angegeben (MyItem in diesem Beispiel). Sie können also auch auf die Property für alle Daten zugreifen, die angezeigt werden sollen.

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

Nachdem Sie die oben genannten Schritte ausgeführt haben, sollte Ihr Code in etwa so aussehen:

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