Karuzela

Karuzela wyświetla przewijaną listę elementów, które dynamicznie dostosowują się do rozmiaru okna. Używaj karuzel, aby prezentować kolekcje powiązanych treści. Elementy karuzeli zawierają przede wszystkim treści 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:

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

Na tej stronie dowiesz się, jak wdrożyć układy karuzeli z wieloma przeglądarkami i bez kontenera. Więcej informacji o typach układu znajdziesz w wytycznych dotyczących karuzeli w Material 3.

Powierzchnia interfejsu API

Aby wdrożyć karuzele z wieloma przeglądaniami i bez kontenera, użyj komponentów HorizontalMultiBrowseCarousel i HorizontalUncontainedCarousel. Te komponenty kompozycyjne mają te same kluczowe parametry:

• state: instancja CarouselState, która zarządza bieżącym indeksem elementów i pozycją przewijania. Utwórz ten stan za pomocą kodu 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 do obszaru treści karuzeli dopełnienie. Użyj tego parametru, aby dodać odstęp przed pierwszym lub po ostatnim elementem albo ustawić marginesy elementów w obszarze przewijania.
• content: funkcja typu „composable”, która przyjmuje 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 (w przypadku HorizontalUncontainedCarousel): określa dokładną szerokość każdego elementu w nieograniczonym karuzeli.
• preferredItemWidth (w przypadku HorizontalMultiBrowseCarousel): sugeruje idealną szerokość elementów w karuzeli z wieloma kartami, dzięki czemu komponent może wyświetlać wiele elementów, jeśli jest na to miejsce.

Przykład: karuzela z wieloma przeglądarkami

Ten fragment kodu implementuje karuzelę z wieloma przeglądarkami:

@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 dla każdego elementu w karuzeli.
• Tworzy i zapamiętuje List obiektów CarouselItem, które są wypełniane zasobami obrazów i opisami.
• Używa komponentu HorizontalMultiBrowseCarousel, który jest przeznaczony do wyświetlania wielu elementów w karuzeli.
  • Stan karuzeli jest inicjowany za pomocą zmiennej rememberCarouselState, której przypisywana jest łączna liczba elementów.
  • Elementy mają wartość preferredItemWidth (w tym przypadku 186.dp), która sugeruje optymalną szerokość każdego elementu. Karuzela używa tej wartości do określania, ile elementów może się zmieścić na ekranie jednocześnie.
  • Parametr itemSpacing dodaje niewielką przerwę między elementami.
  • Ostatnia lambda HorizontalMultiBrowseCarousel iteruje po CarouselItems. W każdej iteracji pobiera element o indeksie i i renderuje dla niego funkcję kompozycyjną Image.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) stosuje do każdego obrazu predefiniowaną maskę kształtu, nadając mu zaokrąglone rogi.
  • contentDescription podaje opis obrazu obsługujący ułatwienia dostępu.

Wynik

Na ilustracji poniżej widać wynik działania powyższego fragmentu kodu:

Przykład: nieograniczony karuzel

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

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

Wynik

Na ilustracji poniżej widać wynik działania powyższego fragmentu kodu: