Băng chuyền

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạ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 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 vào hình ảnh, nhưng cũng có thể chứa văn bản ngắn phù hợp với kích thước 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:

• Xem nhiều: Bao gồm các mặt hàng có kích thước khác nhau. Nên dùng để duyệt qua nhiều mục cùng một 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à chảy 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.
• Hình ảnh chính: Làm nổi bật một hình ảnh lớn để tập trung vào và cung cấp một cái nhìn nhanh về nội dung tiếp theo bằng một mục nhỏ. Bạn nên sử dụng hiệu ứng này để 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ị một mục lớn từ cạnh này sang cạnh kia tại mỗi 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 nhiều chế độ duyệt xem và không chứa. Hãy xem Nguyên tắc về băng chuyền 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 chế độ duyệt xem và 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 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 khu vực nội dung của băng chuyền. 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 có khả năng kết hợp 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 (dành cho HorizontalUncontainedCarousel): Chỉ định chiều rộng chính xác cho mỗi mục trong băng chuyền không có giới hạn.
• preferredItemWidth (dành cho HorizontalMultiBrowseCarousel): Đề xuất chiều rộng lý tưởng cho các mục trong băng chuyền nhiều chế độ duyệt xem, 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 nhiều chế độ xem

Đoạn mã này triển khai băng chuyền nhiều chế độ 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ẽ sắp xếp dữ liệu cho từng phần tử trong băng chuyền.
• Tạo và ghi nhớ 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 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), cho biế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ể vừa với màn hình cùng một lúc.
  • Tham số itemSpacing sẽ thêm một khoảng trống nhỏ giữa các mục.
  • Lambda theo sau của HorizontalMultiBrowseCarousel lặp lại 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à 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ả 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:

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

Đoạn mã sau đây triển khai băng chuyền không có 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 mỗi 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: