Carousel

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

• Multi-browse: Mencakup item dengan ukuran yang berbeda. Direkomendasikan untuk menjelajahi banyak item sekaligus, seperti foto.
• Uncontained: 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 tentang item berikutnya dengan item kecil. Direkomendasikan untuk menyoroti konten yang ingin Anda tekankan, seperti thumbnail film atau acara.
• Layar penuh: Menampilkan satu item besar dari ujung ke ujung dalam satu waktu dan di-scroll secara vertikal. Direkomendasikan untuk konten yang lebih tinggi daripada lebar.

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

Permukaan API

Untuk menerapkan carousel multi-browse dan uncontained, gunakan HorizontalMultiBrowseCarousel dan HorizontalUncontainedCarousel composable. Composable ini memiliki parameter utama berikut:

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

Composable ini berbeda dalam cara menentukan ukuran item:

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

Contoh: Carousel multi-browse

Cuplikan ini mengimplementasikan carousel multi-browse:

@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 parameter ini untuk menentukan jumlah item yang dapat ditampilkan di layar sekaligus.
  • Parameter itemSpacing menambahkan celah kecil di antara item.
  • Lambda akhir HorizontalMultiBrowseCarousel melakukan iterasi melalui CarouselItems. Dalam setiap iterasi, lambda 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 uncontained

Cuplikan berikut mengimplementasikan carousel uncontained:

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