Karuzela

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Karuzela wyświetla przewijaną listę 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 użytkownik ma się skupić, oraz zawiera mały element, który zapowiada, co będzie 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: