Băng chuyền

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

Có 4 bố cục băng chuyền phù hợp với nhiều trường hợp sử dụng:

• Nhiều mục duyệt xem: Bao gồm các mục có kích thước khác nhau. Nên dùng để duyệt xem nhiều mục cùng lúc, chẳng hạn như ảnh.
• Không chứa: Chứa các mục có kích thước duy nhất và tràn ra ngoài 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 phía dưới mỗi mục.
• Hero: Làm nổi bật một hình ảnh lớn để tập trung vào và cung cấp thông tin sơ lược về 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.
• Toàn màn hình: Hiển thị từng mục lớn tràn viền 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.

Hình 1. Các loại băng chuyền không có vùng chứa (1) và toàn màn hình (2).

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

Nền tảng API

Để triển khai băng chuyền nhiều trình duyệt và băng chuyền không chứa, 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ó chung 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. Hãy sử dụng thuộc tính 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: 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 một băng chuyền không chứa.
• preferredItemWidth (cho HorizontalMultiBrowseCarousel): Đề xuất chiều rộng lý tưởng cho các mục trong băng chuyền nhiều mục duyệt xem, cho phép thành phần hiển thị nhiều mục nếu không gian cho phép.

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

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

@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 một lớp dữ liệu CarouselItem, lớp này sẽ 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ủa các đối tượng CarouselItem được điền sẵn 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 một băng chuyền.
  • Trạng thái của băng chuyền được khởi chạy bằ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 mỗi mục. Băng chuyền sử dụng thông tin này để xác định số lượng mục có thể hiển thị trên 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.
  • Trailing lambda của HorizontalMultiBrowseCarousel lặp lại thông qua CarouselItems. Trong mỗi lần lặp lại, hàm này sẽ truy xuất mục tại chỉ mục i và kết xuất một thành phần kết hợp Image cho mục đó.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) áp dụng một 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ả hỗ trợ tiếp cận cho hình ảnh.

Kết quả

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

Hình 2. Băng chuyền nhiều mục, trong đó mục cuối cùng bị cắt bớt.

Ví dụ: Băng chuyền không có vùng chứa

Đoạn mã sau đây triển khai một băng chuyền không chứa:

@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ả của đoạn mã trước:

Hình 3. Băng chuyền không chứa, trong đó mục cuối cùng trong băng chuyền không bị cắt bớt.