Karuzela

Karuzela wyświetla przewijaną listę elementów, która dynamicznie dostosowuje się do rozmiaru okna. Używaj karuzel, aby prezentować kolekcję powiązanych artykułów. Elementy karuzeli kładą nacisk na elementy wizualne, ale mogą też zawierać krótki tekst, który dostosowuje się do rozmiaru elementu.

Dostępne są 4 układy karuzeli, które pasują do różnych przypadków użycia:

• Wiele rozmiarów: obejmuje elementy o różnych rozmiarach. Zalecany do przeglądania wielu elementów naraz, np. zdjęć.
• Bez kontenera: zawiera elementy o jednym rozmiarze, które wykraczają poza krawędź ekranu. Można go dostosować, aby wyświetlał więcej tekstu lub inne elementy interfejsu nad lub pod każdym elementem.
• Hero: wyróżnia jeden duży obraz, na którym można się skupić, i pokazuje, co będzie dalej, za pomocą małego elementu. Zalecane do wyróżniania treści, które chcesz podkreślić, np. miniatur filmów lub programów.
• Pełny ekran: pokazuje po jednym dużym elemencie od krawędzi do krawędzi i przewija się w pionie. Zalecane w przypadku treści, które są wyższe niż szersze.

Na tej stronie dowiesz się, jak wdrożyć układy karuzeli z wieloma opcjami przeglądania i bez ograniczeń. Więcej informacji o typach układów znajdziesz w wytycznych dotyczących karuzeli w Material 3.

Interfejs API

Aby zaimplementować karuzelę z wieloma elementami i karuzelę bez kontenera, użyj funkcji kompozycyjnych HorizontalMultiBrowseCarousel i HorizontalUncontainedCarousel. Te funkcje kompozycyjne 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ą rememberCarouselState { itemCount }, gdzie itemCount to łączna liczba elementów w karuzeli.
• itemSpacing: określa ilość pustego miejsca między sąsiadującymi elementami w karuzeli.
• contentPadding: stosuje dopełnienie wokół obszaru zawartości karuzeli. Użyj tej opcji, aby dodać miejsce przed pierwszym elementem lub po ostatnim elemencie albo aby ustawić marginesy dla elementów w obszarze przewijania.
• content: funkcja typu „composable”, która otrzymuje indeks liczby całkowitej. Użyj tej funkcji lambda, aby zdefiniować interfejs każdego elementu w karuzeli na podstawie jego indeksu.

Te funkcje kompozycyjne różnią się sposobem określania rozmiaru elementu:

• itemWidth (dla HorizontalUncontainedCarousel): określa dokładną szerokość każdego elementu w karuzeli bez kontenera.
• preferredItemWidth (dla HorizontalMultiBrowseCarousel): sugeruje idealną szerokość elementów w karuzeli z wieloma elementami, umożliwiając komponentowi wyświetlanie wielu elementów, jeśli pozwala na to miejsce.

Przykład: karuzela z wieloma opcjami przeglądania

Ten fragment kodu implementuje karuzelę z wieloma opcjami przeglądania:

@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 porządkuje dane dla 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 funkcji kompozycyjnej HorizontalMultiBrowseCarousel, która jest przeznaczona do wyświetlania wielu elementów w karuzeli.
  • Stan karuzeli jest inicjowany za pomocą funkcji rememberCarouselState, która otrzymuje łączną liczbę elementów.
  • Elementy mają właściwość preferredItemWidth (tutaj: 186.dp), która sugeruje optymalną szerokość każdego elementu. Karuzela używa tej wartości, aby określić, ile elementów może zmieścić się na ekranie jednocześnie.
  • Parametr itemSpacing dodaje niewielką przerwę między elementami.
  • Ostatnie wyrażenie lambda HorizontalMultiBrowseCarousel iteruje po CarouselItems. W każdej iteracji pobiera element o indeksie i i renderuje dla niego element kompozycyjny Image.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) stosuje do każdego obrazu wstępnie zdefiniowaną maskę kształtu, nadając mu zaokrąglone rogi.
  • contentDescription zawiera opis obrazu dla ułatwień dostępu.

Wynik

Poniższy obraz przedstawia wynik poprzedniego fragmentu kodu:

Przykład: karuzela bez kontenera

Poniższy fragment kodu implementuje karuzelę bez kontenera:

@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

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

Wynik

Poniższy obraz przedstawia wynik poprzedniego fragmentu kodu: