Băng chuyền

Băng chuyền hiển thị một danh sách các mục có thể cuộn và tự động điều chỉnh dựa trên kích thước cửa sổ. Hãy sử dụng băng chuyền để giới thiệu một bộ sưu tập nội dung có liên quan. Các mục trong băng chuyền nhấn mạnh hình ảnh, nhưng cũng có thể chứa văn bản ngắn gọn điều chỉnh theo kích thước mục.

Có 4 bố cục băng chuyền để phù hợp với các trường hợp sử dụng khác nhau:

• Multi-browse (Duyệt nhiều mục): Bao gồm các mục có kích thước khác nhau. Nên dùng để duyệt nhiều mục cùng một lúc, chẳng hạn như ảnh.
• Không giới hạn: Chứa các mục có cùng kích thước và trượt qua cạnh màn hình. Có thể tuỳ chỉnh để hiển thị thêm văn bản hoặc giao diện người dùng khác phía trên hoặc bên dưới mỗi mục.
• Hero (Nổi bật): Làm nổi bật một hình ảnh lớn để tập trung vào và cho thấy trước nội dung tiếp theo bằng một mục nhỏ. Nên dùng để làm nổi bật nội dung mà bạn muốn nhấn mạnh, chẳng hạn như hình thu nhỏ của phim hoặc chương trình.
• Full-screen (Toàn màn hình): Hiển thị một mục lớn từ cạnh này sang cạnh khác tại một thời điểm và cuộn theo chiều dọc. Nên dùng cho nội dung có chiều cao lớn hơn chiều rộng.

Trang này hướng dẫn bạn cách triển khai bố cục băng chuyền không giới hạn và duyệt nhiều mục. Hãy xem nguyên tắc Băng chuyền Material 3 để biết thêm thông tin về các loại bố cục.

Bề mặt API

Để triển khai băng chuyền không giới hạn và duyệt nhiều mục, hãy sử dụng các thành phần kết hợp HorizontalMultiBrowseCarousel và HorizontalUncontainedCarousel. Các thành phần kết hợp này có các tham số chính sau:

• state: Một thực thể CarouselState quản lý chỉ mục mục hiện tại và vị trí cuộn. Tạo trạng thái này bằng cách sử dụng rememberCarouselState { itemCount }, trong đó itemCount là tổng số mục trong băng chuyền.
• itemSpacing: Xác định khoảng trống giữa các mục liền kề trong băng chuyền.
• contentPadding: Áp dụng khoảng đệm xung quanh vùng nội dung của băng chuyền. Sử dụng tham số này để thêm khoảng trống trước mục đầu tiên hoặc sau mục cuối cùng, hoặc để cung cấp lề cho các mục trong vùng có thể cuộn.
• content: Một hàm composable nhận chỉ mục số nguyên. Sử dụng lambda này để xác định giao diện người dùng cho từng mục trong băng chuyền dựa trên chỉ mục của mục đó.

Các thành phần kết hợp này khác nhau về cách chỉ định kích thước mục:

• itemWidth (cho HorizontalUncontainedCarousel): Chỉ định chiều rộng chính xác cho từng mục trong băng chuyền không giới hạn.
• preferredItemWidth (cho HorizontalMultiBrowseCarousel): Đề xuất chiều rộng lý tưởng cho các mục trong băng chuyền duyệt nhiều mục, cho phép thành phần hiển thị nhiều mục nếu có đủ không gian.

Ví dụ: Băng chuyền duyệt nhiều mục

Đoạn mã này triển khai băng chuyền duyệt nhiều mục:

@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

Các điểm chính về mã

• Xác định lớp dữ liệu CarouselItem, cấu trúc dữ liệu cho từng phần tử trong băng chuyền.
• Tạo và ghi nhớ một List các đối tượng CarouselItem được điền bằng tài nguyên hình ảnh và nội dung mô tả.
• Sử dụng thành phần kết hợp HorizontalMultiBrowseCarousel, được thiết kế để hiển thị nhiều mục trong băng chuyền.
  • Trạng thái của băng chuyền được khởi chạy bằng cách sử dụng rememberCarouselState, được cung cấp tổng số mục.
  • Các mục có preferredItemWidth (ở đây là 186.dp), đề xuất chiều rộng tối ưu cho từng mục. Băng chuyền sử dụng tham số này để xác định số lượng mục có thể vừa với màn hình cùng một lúc.
  • Tham số itemSpacing thêm một khoảng trống nhỏ giữa các mục.
  • Lambda cuối của HorizontalMultiBrowseCarousel lặp lại thông qua CarouselItems. Trong mỗi lần lặp, lambda này sẽ truy xuất mục tại chỉ mục i và hiển thị một thành phần kết hợp Image cho mục đó.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) áp dụng mặt nạ hình dạng được xác định trước cho mỗi hình ảnh, tạo cho hình ảnh đó các góc bo tròn.
  • contentDescription cung cấp nội dung mô tả về khả năng tiếp cận cho hình ảnh.

Kết quả

Hình ảnh sau đây cho thấy kết quả từ đoạn mã trước đó:

Ví dụ: Băng chuyền không giới hạn

Đoạn mã sau đây triển khai băng chuyền không giới hạn:

@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

Các điểm chính về mã

• Thành phần kết hợp HorizontalUncontainedCarousel tạo bố cục băng chuyền.
  • Tham số itemWidth đặt chiều rộng cố định cho từng mục trong băng chuyền.

Kết quả

Hình ảnh sau đây cho thấy kết quả từ đoạn mã trước đó: