Karussell

In einem Karussell wird eine scrollbare Liste von Elementen angezeigt, die sich dynamisch an die Fenstergröße anpassen. Karussells eignen sich gut, um eine Sammlung verwandter Inhalte zu präsentieren. Karussellelemente betonen visuelle Elemente, können aber auch kurzen Text enthalten, der an die Elementgröße angepasst wird.

Es gibt vier Karussell-Layouts für verschiedene Anwendungsfälle:

• Multi-Browse: Enthält Elemente unterschiedlicher Größe. Empfohlen, um viele Elemente gleichzeitig zu durchsuchen, z. B. Fotos.
• Uncontained: Enthält Elemente mit einer einheitlichen Größe, die über den Bildschirmrand hinauslaufen. Kann so angepasst werden, dass über oder unter jedem Element mehr Text oder andere UI-Elemente angezeigt werden.
• Hero: Hebt ein großes Bild hervor und bietet mit einem kleinen Element einen Einblick in das, was als Nächstes kommt. Empfohlen, um Inhalte hervorzuheben, die Sie betonen möchten, z. B. Film- oder Serienvorschaubilder.
• Full-Screen: Zeigt jeweils ein großes Element von Rand zu Rand an und scrollt vertikal. Empfohlen für Inhalte, die höher als breit sind.

Auf dieser Seite erfahren Sie, wie Sie die Karussell-Layouts „Multi-Browse“ und „Uncontained“ implementieren. Weitere Informationen zu den Layouttypen finden Sie in den Material 3-Richtlinien für Karussells.

API-Oberfläche

Verwenden Sie die HorizontalMultiBrowseCarousel und HorizontalUncontainedCarousel zusammensetzbaren Funktionen, um Karussells vom Typ „Multi-Browse“ und „Uncontained“ zu implementieren. Diese zusammensetzbaren Funktionen haben die folgenden gemeinsamen Parameter:

• state: Eine CarouselState-Instanz, die den aktuellen Elementindex und die Scrollposition verwaltet. Erstellen Sie diesen Status mit rememberCarouselState { itemCount }, wobei itemCount die Gesamtzahl der Elemente im Karussell ist.
• itemSpacing: Definiert den Abstand zwischen benachbarten Elementen im Karussell.
• contentPadding: Fügt einen Abstand um den Inhaltsbereich des Karussells hinzu. Damit können Sie vor dem ersten oder nach dem letzten Element Platz hinzufügen oder Ränder für die Elemente im scrollbaren Bereich festlegen.
• content: Eine zusammensetzbare Funktion, die einen ganzzahligen Index empfängt. Mit dieser Lambda-Funktion können Sie die UI für jedes Element im Karussell basierend auf seinem Index definieren.

Diese zusammensetzbaren Funktionen unterscheiden sich in der Art und Weise, wie die Elementgröße angegeben wird:

• itemWidth (für HorizontalUncontainedCarousel): Gibt die genaue Breite für jedes Element in einem Karussell vom Typ „Uncontained“ an.
• preferredItemWidth (für HorizontalMultiBrowseCarousel): Schlägt die ideale Breite für Elemente in einem Karussell vom Typ „Multi-Browse“ vor, sodass die Komponente mehrere Elemente anzeigen kann, wenn genügend Platz vorhanden ist.

Beispiel: Karussell vom Typ „Multi-Browse“

Dieses Snippet implementiert ein Karussell vom Typ „Multi-Browse“:

@Composable
fun CarouselExample_MultiBrowse() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val items = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalMultiBrowseCarousel(
        state = rememberCarouselState { items.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        preferredItemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = items[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

Wichtige Informationen zum Code

• Definiert eine CarouselItem-Datenklasse, die die Daten für jedes Element im Karussell strukturiert.
• Erstellt und speichert eine List von CarouselItem-Objekten, die mit Bildressourcen und Beschreibungen gefüllt sind.
• Verwendet die zusammensetzbare Funktion HorizontalMultiBrowseCarousel, die für die Anzeige mehrerer Elemente in einem Karussell entwickelt wurde.
  • Der Status des Karussells wird mit rememberCarouselState initialisiert, dem die Gesamtzahl der Elemente übergeben wird.
  • Elemente haben eine preferredItemWidth (hier 186.dp), die eine optimale Breite für jedes Element vorschlägt. Das Karussell verwendet diese Breite, um zu bestimmen, wie viele Elemente gleichzeitig auf dem Bildschirm angezeigt werden können.
  • Der Parameter itemSpacing fügt einen kleinen Abstand zwischen den Elementen hinzu.
  • Die nachgestellte Lambda-Funktion von HorizontalMultiBrowseCarousel durchläuft die CarouselItems. In jeder Iteration wird das Element mit dem Index i abgerufen und eine zusammensetzbare Funktion Image dafür gerendert.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) wendet eine vordefinierte Formmaske auf jedes Bild an, wodurch es abgerundete Ecken erhält.
  • contentDescription bietet eine Beschreibung für die Bedienungshilfe für das Bild.

Ergebnis

Die folgende Abbildung zeigt das Ergebnis des vorherigen Snippets:

Beispiel: Karussell vom Typ „Uncontained“

Das folgende Snippet implementiert ein Karussell vom Typ „Uncontained“:

@Composable
fun CarouselExample() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val carouselItems = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalUncontainedCarousel(
        state = rememberCarouselState { carouselItems.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        itemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = carouselItems[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

Wichtige Informationen zum Code

• Die zusammensetzbare Funktion HorizontalUncontainedCarousel erstellt das Karussell-Layout.
  • Der Parameter itemWidth legt eine feste Breite für jedes Element im Karussell fest.

Ergebnis

Die folgende Abbildung zeigt das Ergebnis des vorherigen Snippets: