Karuzela

Karuzela to przewijalna lista elementów, które dostosowują się dynamicznie do rozmiaru okna. Korzystaj z karuzel, aby prezentować kolekcje powiązanych treści. Elementy karuzeli zawierają głównie elementy wizualne, ale mogą też zawierać krótki tekst, który dostosowuje się do rozmiaru elementu.

Dostępne są 4 układy karuzeli dopasowane do różnych zastosowań:

• Wiele przeglądarek: obejmuje produkty o różnych rozmiarach. Zalecane do przeglądania wielu elementów jednocześnie, np. zdjęć.
• Bez ograniczeń: zawiera elementy o jednym rozmiarze, które wystają poza krawędź ekranu. Możesz go dostosować, aby wyświetlał więcej tekstu lub inny interfejs nad każdym elementem.
• Główny: wyróżnia jedno duże zdjęcie, na którym można się skupić, oraz zawiera mały element z przeglądem tego, co znajduje się dalej. Zalecane do wyróżniania treści, które chcesz podkreślić, takich jak miniatury filmów lub programów.
• Pełny ekran: wyświetla jeden duży element na pełnym ekranie i przewija w pionie. Zalecane dla treści, które są wyższe niż szersze.

Na tej stronie znajdziesz informacje o wdrażaniu układów z wielokrotnie wyświetlanymi kartami i bez ograniczeń. Więcej informacji o typach układów znajdziesz w wytycznych dotyczących karuzeli Material 3.

Interfejs API

Aby wdrożyć przeglądarki wielozadaniowe i karuzele bez ograniczeń, użyj komponentów HorizontalMultiBrowseCarousel i HorizontalUncontainedCarousel. Te komponenty mają te same kluczowe parametry:

• state: instancja CarouselState, która zarządza bieżącym indeksem elementu i pozycją przewijania. Utwórz ten stan za pomocą parametru rememberCarouselState { itemCount }, gdzie itemCount to łączna liczba elementów w karuzeli.
• itemSpacing: określa ilość pustego miejsca między sąsiednimi elementami w karuzeli.
• contentPadding: stosuje wypełnienie wokół obszaru treści karuzeli. Użyj tego, aby dodać odstęp przed pierwszym elementem lub po ostatnim elemencie albo aby zapewnić marginesy dla elementów w regionie przewijania.
• content: funkcja typu „composable”, która przyjmuje indeks całkowity. Użyj tej funkcji lambda, aby zdefiniować interfejs dla każdego elementu w karuzeli na podstawie jego indeksu.

Te komponenty różnią się sposobem określania rozmiaru elementów:

• itemWidth (dla HorizontalUncontainedCarousel): określa dokładną szerokość każdego elementu w nieograniczonym karuzeli.
• preferredItemWidth (dla HorizontalMultiBrowseCarousel): sugeruje idealną szerokość elementów w karuzeli z wieloma przeglądami, umożliwiając komponentowi wyświetlanie wielu elementów, jeśli pozwala na to dostępna przestrzeń.

Przykład: karuzela z wieloma przeglądami

Ten fragment kodu implementuje karuzel z wieloma przeglądami:

@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

Najważniejsze informacje o kodzie

• Definiuje klasę danych CarouselItem, która strukturyzuje dane każdego elementu w karuzeli.
• Tworzy i zapamiętuje List obiektów CarouselItem, które są wypełnione zasobami obrazów i opisami.
• Używa komponentu HorizontalMultiBrowseCarousel, który służy do wyświetlania wielu elementów w karuzeli.
  • Stan karuzeli jest inicjowany za pomocą funkcji rememberCarouselState, która zwraca łączną liczbę elementów.
  • Elementy mają atrybut preferredItemWidth (tutaj 186.dp), który sugeruje optymalną szerokość każdego z nich. Karuzelę wykorzystuje tę wartość do określenia, ile elementów może się zmieścić na ekranie jednocześnie.
  • Parametr itemSpacing dodaje niewielką przerwę między elementami.
  • Ostatnia lambda w funkcji HorizontalMultiBrowseCarousel iteruje po CarouselItems. W każdej iteracji pobiera element o indeksie i i renderuje dla niego kompozyt Image.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) stosuje do każdego obrazu gotową maskę kształtu, nadając mu zaokrąglone rogi.
  • contentDescription zawiera opis obrazu obsługujący ułatwienia dostępu.

Wynik

Ten obraz przedstawia wynik z poprzedniego fragmentu kodu:

Przykład: nieograniczone karuzele

Ten fragment kodu wdraża karuzel bez ograniczeń:

@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

Najważniejsze informacje o kodzie

• Komponent HorizontalUncontainedCarousel tworzy układ karuzeli.
  • Parametr itemWidth ustawia stałą szerokość każdego elementu w karuzeli.

Wynik

Ten obraz przedstawia wynik z poprzedniego fragmentu kodu: