Karuzela

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

• Wielokrotne przeglądanie: zawiera elementy o różnych rozmiarach. Zalecane do przeglądania wielu elementów naraz, np. zdjęć.
• Nieograniczone: zawiera elementy o jednym rozmiarze, które przesuwają się poza krawędź ekranu. Można je dostosować tak, aby wyświetlać więcej tekstu lub innych elementów interfejsu nad lub pod każdym elementem.
• Główne: wyróżnia 1 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łnoekranowe: wyświetla 1 duży element od krawędzi do krawędzi i przewija go 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 wielokrotnym przeglądaniem i nieograniczone. Więcej informacji o typach układów znajdziesz w wytycznych dotyczących karuzeli Material 3.

Powierzchnia API

Aby wdrożyć karuzele z wielokrotnym przeglądaniem i nieograniczone, użyj funkcji typu „composable” HorizontalMultiBrowseCarousel i HorizontalUncontainedCarousel. Te funkcje typu „composable” 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ąsiednimi elementami w karuzeli.
• contentPadding: stosuje dopełnienie wokół obszaru treści karuzeli. Użyj tego parametru, aby dodać miejsce przed pierwszym lub po ostatnim elemencie albo aby dodać marginesy do elementów w przewijanym regionie.
• content: funkcja typu „composable”, która przyjmuje indeks całkowity. Użyj tej lambdy, aby zdefiniować interfejs każdego elementu w karuzeli na podstawie jego indeksu.

Te funkcje typu „composable” różnią się sposobem określania rozmiaru elementu:

• itemWidth (w przypadku HorizontalUncontainedCarousel): określa dokładną szerokość każdego elementu w nieograniczonej karuzeli.
• preferredItemWidth (w przypadku HorizontalMultiBrowseCarousel): sugeruje idealną szerokość elementów w karuzeli z wielokrotnym przeglądaniem, umożliwiając komponentowi wyświetlanie wielu elementów, jeśli jest na to miejsce.

Przykład: karuzela z wielokrotnym przeglądaniem

Ten fragment kodu implementuje karuzelę z wielokrotnym przeglądaniem:

@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 określa strukturę danych 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 funkcji typu „composable” HorizontalMultiBrowseCarousel, która jest przeznaczona do wyświetlania wielu elementów w karuzeli.
  • Stan karuzeli jest inicjowany za pomocą rememberCarouselState, która otrzymuje łączną liczbę elementów.
  • Elementy mają preferredItemWidth (w tym przypadku 186.dp), która sugeruje optymalną szerokość każdego elementu. Karuzela używa tego parametru, aby określić, ile elementów może się zmieścić na ekranie naraz.
  • Parametr itemSpacing dodaje niewielką przerwę między elementami.
  • Lambda końcowa HorizontalMultiBrowseCarousel iteruje po CarouselItems. W każdej iteracji pobiera element o indeksie i i renderuje dla niego funkcję typu „composable” Image.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) stosuje do każdego obrazu predefiniowaną maskę kształtu, nadając mu zaokrąglone rogi.
  • contentDescription zawiera opis ułatwień dostępu do obrazu.

Wynik

Na tym obrazie widać wynik działania poprzedniego fragmentu kodu:

Przykład: nieograniczona karuzela

Ten fragment kodu implementuje nieograniczoną karuzelę:

@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 typu „composable” HorizontalUncontainedCarousel tworzy układ karuzeli.
  • Parametr itemWidth ustawia stałą szerokość każdego elementu w karuzeli.

Wynik

Na tym obrazie widać wynik działania poprzedniego fragmentu kodu: