Karussell

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

Es sind vier Karussell-Layouts für verschiedene Anwendungsfälle verfügbar:

• Multi-Browse: Enthält Elemente unterschiedlicher Größe. Empfohlen, wenn Sie viele Elemente gleichzeitig durchsuchen möchten, z. B. Fotos.
• Uncontained: Enthält Elemente, die eine einheitliche Größe haben und über den Bildschirmrand hinausgehen. Kann angepasst werden, um mehr Text oder andere UI-Elemente über oder unter jedem Element anzuzeigen.
• Hero: Hebt ein großes Bild hervor, auf das der Fokus gelegt werden soll, und bietet mit einem kleinen Element einen Einblick in das, was als Nächstes kommt. Empfohlen, um Inhalte hervorzuheben, die du betonen möchtest, z. B. Miniaturansichten von Filmen oder Serien.
• Vollbild: Es wird jeweils ein großes Element im Vollbildmodus angezeigt und vertikal gescrollt. Empfohlen für Inhalte, die höher als breit sind.

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

API-Oberfläche

Wenn Sie Karussells mit mehreren Elementen und ohne Container implementieren möchten, verwenden Sie die Composables HorizontalMultiBrowseCarousel und HorizontalUncontainedCarousel. Diese Composables haben die folgenden Schlüsselparameter gemeinsam:

• state: Eine CarouselState-Instanz, die den aktuellen Elementindex und die Scrollposition verwaltet. Erstelle diesen Status mit rememberCarouselState { itemCount }, wobei itemCount die Gesamtzahl der Elemente im Karussell ist.
• itemSpacing: Definiert den Abstand zwischen benachbarten Elementen im Karussell.
• contentPadding: Wendet einen Abstand um den Inhaltsbereich des Karussells an. 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. Verwenden Sie diesen Lambda-Ausdruck, um die UI für jedes Element im Karussell basierend auf seinem Index zu definieren.

Diese Composables unterscheiden sich darin, wie sie die Elementgröße angeben:

• itemWidth (für HorizontalUncontainedCarousel): Gibt die genaue Breite für jedes Element in einem Karussell ohne Container an.
• preferredItemWidth (für HorizontalMultiBrowseCarousel): Schlägt die ideale Breite für Elemente in einem Multi-Browse-Karussell vor, sodass die Komponente mehrere Elemente anzeigen kann, wenn der Platz es zulässt.

Beispiel: Karussell mit mehreren Suchergebnissen

Dieses Snippet implementiert ein Karussell mit mehreren Suchergebnissen:

@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 eine List von CarouselItem-Objekten, die mit Bildressourcen und Beschreibungen gefüllt sind, und merkt sich diese.
• Verwendet die komponierbare Funktion HorizontalMultiBrowseCarousel, die für die Anzeige mehrerer Elemente in einem Karussell konzipiert ist.
  • Der Status des Karussells wird mit rememberCarouselState initialisiert, wobei die Gesamtzahl der Elemente angegeben wird.
  • 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 den Bildschirm passen.
  • Mit dem Parameter itemSpacing wird ein kleiner Abstand zwischen den Elementen eingefügt.
  • Das nachgestellte Lambda von HorizontalMultiBrowseCarousel iteriert durch die CarouselItems. In jeder Iteration wird das Element am Index i abgerufen und ein Image-Composable dafür gerendert.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) wendet auf jedes Bild eine vordefinierte Formmaske an, sodass es abgerundete Ecken erhält.
  • contentDescription stellt eine Beschreibung der Barrierefreiheit für das Bild bereit.

Ergebnis

Die folgende Abbildung zeigt das Ergebnis des vorherigen Snippets:

Beispiel: Karussell ohne Container

Im folgenden Snippet wird ein Karussell ohne Container implementiert:

@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 HorizontalUncontainedCarousel komponierbare Funktion erstellt das Karussell-Layout.
  • Mit dem Parameter itemWidth wird für jedes Element im Karussell eine feste Breite festgelegt.

Ergebnis

Die folgende Abbildung zeigt das Ergebnis des vorherigen Snippets: