Carousel

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Carousel menampilkan daftar item yang dapat di-scroll yang 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 berbagai kasus penggunaan:

• Multi-penjelajahan: Mencakup item dengan ukuran berbeda. Direkomendasikan untuk menjelajahi banyak item sekaligus, seperti foto.
• Tidak dibatasi: Berisi item yang memiliki satu ukuran dan mengalir melewati tepi layar. Dapat disesuaikan untuk menampilkan lebih banyak teks atau UI lainnya di atas atau di bawah setiap item.
• Banner besar: Menyoroti satu gambar besar untuk difokuskan dan memberikan sekilas tentang hal berikutnya dengan item kecil. Direkomendasikan untuk menyoroti konten yang ingin Anda tekankan, seperti thumbnail film atau acara TV.
• Layar penuh: Menampilkan satu item besar dari tepi ke tepi sekaligus dan men-scroll secara vertikal. Direkomendasikan untuk konten yang lebih tinggi daripada lebarnya.

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

Platform API

Untuk menerapkan carousel multi-penjelajahan dan tanpa batas, 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 di 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 untuk item dalam wilayah yang dapat di-scroll.
• content: Fungsi composable yang menerima indeks bilangan bulat. Gunakan lambda ini untuk menentukan UI untuk setiap item di carousel berdasarkan indeksnya.

Composable ini berbeda dalam cara menentukan ukuran item:

• itemWidth (untuk HorizontalUncontainedCarousel): Menentukan lebar yang tepat untuk setiap item dalam carousel yang tidak dibatasi.
• preferredItemWidth (untuk HorizontalMultiBrowseCarousel): Menyarankan lebar ideal untuk item dalam carousel multi-penjelajahan, sehingga komponen dapat menampilkan beberapa item jika ruang memungkinkan.

Contoh: Korsel multi-penjelajahan

Cuplikan ini menerapkan 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-poin penting tentang kode

• Menentukan class data CarouselItem, yang menyusun data untuk setiap elemen di carousel.
• Membuat dan mengingat List objek CarouselItem yang diisi dengan deskripsi dan resource 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, metode ini mengambil item pada indeks i dan merender composable Image untuknya.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) menerapkan mask 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: Carousel tanpa batasan

Cuplikan berikut mengimplementasikan carousel yang tidak dibatasi:

@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-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: