Carousel

Carousel menampilkan daftar item yang dapat di-scroll dan beradaptasi secara dinamis berdasarkan ukuran jendela. Gunakan carousel untuk menampilkan koleksi konten terkait. Item carousel menekankan visual, tetapi juga dapat berisi teks singkat yang menyesuaikan dengan ukuran item.

Ada empat tata letak carousel yang tersedia untuk disesuaikan dengan berbagai kasus penggunaan:

• Multi-browse: Mencakup item dengan ukuran berbeda. Direkomendasikan untuk menjelajahi banyak item sekaligus, seperti foto.
• Tidak terbatas: Berisi item yang berukuran tunggal dan mengalir melewati tepi layar. Dapat disesuaikan untuk menampilkan lebih banyak teks atau UI lainnya di atas atau di bawah setiap item.
• Hero: Menyoroti satu gambar besar untuk difokuskan dan memberikan gambaran sekilas tentang apa yang akan terjadi selanjutnya dengan item kecil. Direkomendasikan untuk menyoroti konten yang ingin Anda tekankan, seperti thumbnail film atau acara.
• Layar penuh: Menampilkan satu item besar dari tepi ke tepi sekaligus dan men-scroll secara vertikal. Direkomendasikan untuk konten yang tingginya lebih besar daripada lebarnya.

Halaman ini menunjukkan cara menerapkan tata letak multi-browse dan carousel uncontained. Lihat Panduan Carousel Material 3 untuk mengetahui informasi selengkapnya tentang jenis tata letak.

Platform API

Untuk menerapkan carousel multi-jelajah dan tidak terbatas, gunakan composable HorizontalMultiBrowseCarousel dan HorizontalUncontainedCarousel. Composable ini memiliki parameter utama berikut:

• state: Instance CarouselState yang mengelola indeks item dan posisi scroll saat ini. Buat status ini menggunakan rememberCarouselState { itemCount }, dengan itemCount adalah jumlah total item dalam carousel.
• itemSpacing: Menentukan jumlah ruang kosong di antara item yang berdekatan dalam carousel.
• contentPadding: Menerapkan padding di sekitar area konten carousel. Gunakan ini untuk menambahkan spasi sebelum item pertama atau setelah item terakhir, atau untuk memberikan margin bagi item dalam region yang dapat di-scroll.
• content: Fungsi composable yang menerima indeks bilangan bulat. Gunakan lambda ini untuk menentukan UI setiap item dalam carousel berdasarkan indeksnya.

Composable ini berbeda dalam cara menentukan ukuran item:

• itemWidth (untuk HorizontalUncontainedCarousel): Menentukan lebar persis untuk setiap item dalam carousel tanpa penampung.
• preferredItemWidth (untuk HorizontalMultiBrowseCarousel): Menyarankan lebar ideal untuk item dalam carousel multi-jelajah, sehingga komponen dapat menampilkan beberapa item jika ruang memungkinkan.

Contoh: Carousel multi-penjelajahan

Cuplikan ini mengimplementasikan carousel multi-penjelajahan:

@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

Poin penting tentang kode

• Menentukan class data CarouselItem, yang menyusun data untuk setiap elemen dalam carousel.
• Membuat dan mengingat List objek CarouselItem yang diisi dengan resource dan deskripsi gambar.
• Menggunakan composable HorizontalMultiBrowseCarousel, yang dirancang untuk menampilkan beberapa item dalam carousel.
  • Status carousel diinisialisasi menggunakan rememberCarouselState, yang diberi jumlah total item.
  • Item memiliki preferredItemWidth (di sini, 186.dp), yang menyarankan lebar optimal untuk setiap item. Carousel menggunakan ini untuk menentukan jumlah item yang dapat muat di layar sekaligus.
  • Parameter itemSpacing menambahkan celah kecil di antara item.
  • Lambda akhir HorizontalMultiBrowseCarousel melakukan iterasi melalui CarouselItems. Dalam setiap iterasi, fungsi ini mengambil item di indeks i dan merender composable Image untuk item tersebut.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) menerapkan masker bentuk yang telah ditentukan ke setiap gambar, sehingga memberikan sudut membulat.
  • contentDescription memberikan deskripsi aksesibilitas untuk gambar.

Hasil

Gambar berikut menunjukkan hasil dari cuplikan sebelumnya:

Contoh: Contoh: Carousel tanpa penampung

Cuplikan berikut mengimplementasikan carousel tanpa penampung:

@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

Poin penting tentang kode

• Composable HorizontalUncontainedCarousel membuat tata letak carousel.
  • Parameter itemWidth menetapkan lebar tetap untuk setiap item dalam carousel.

Hasil

Gambar berikut menunjukkan hasil dari cuplikan sebelumnya: