Karussell

In einem Karussell wird eine scrollbare Liste von Elementen angezeigt, die dynamisch an die Fenstergröße angepasst werden. Mit Karussells können Sie eine Sammlung verwandter Inhalte 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 eine Vorschau auf das nächste Element. Empfohlen, um Inhalte hervorzuheben, die Sie betonen möchten, z. B. Film- oder Serien-Thumbnails.
• 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 Schlüsselparameter:

• state: Eine CarouselState-Instanz, die den aktuellen Elementindex und die aktuelle 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. Verwenden Sie diese Option, um vor dem ersten oder nach dem letzten Element Platz hinzuzufügen oder um Ränder für die Elemente im scrollbaren Bereich festzulegen.
• 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 Punkte 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, wobei die Gesamtzahl der Elemente angegeben wird.
  • Die Elemente haben eine preferredItemWidth (hier 186.dp), die eine optimale Breite für jedes Element vorschlägt. Das Karussell verwendet diese Angabe, 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 Punkte 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: