ภาพสไลด์จะแสดงรายการที่เลื่อนได้ซึ่งปรับเปลี่ยนแบบไดนามิกตามขนาดหน้าต่าง ใช้ภาพสไลด์เพื่อแสดงคอลเล็กชันเนื้อหาที่เกี่ยวข้อง รายการภาพสไลด์เน้นภาพ แต่ก็อาจมีข้อความสั้นๆ ที่ปรับให้เข้ากับขนาดของรายการได้ด้วย
เลย์เอาต์ภาพสไลด์มี 4 แบบให้เลือกใช้ตามกรณีการใช้งานต่างๆ ดังนี้
- การเรียกดูหลายรายการ: มีสินค้าขนาดแตกต่างกัน แนะนำสำหรับการเรียกดู หลายรายการพร้อมกัน เช่น รูปภาพ
- ไม่จำกัด: มีรายการที่มีขนาดเดียวและไหลผ่านขอบ ของหน้าจอ ปรับแต่งให้แสดงข้อความหรือ UI อื่นๆ เพิ่มเติมเหนือหรือใต้ แต่ละรายการได้
- ฮีโร่: ไฮไลต์รูปภาพขนาดใหญ่ 1 รูปเพื่อโฟกัส และแสดงตัวอย่างของสิ่งที่ จะเกิดขึ้นต่อไปด้วยรายการขนาดเล็ก แนะนำสำหรับไฮไลต์เนื้อหาที่คุณต้องการ เน้น เช่น ภาพขนาดย่อของภาพยนตร์หรือรายการ
- เต็มหน้าจอ: แสดงรายการขนาดใหญ่แบบขอบจรดขอบทีละรายการและเลื่อน ในแนวตั้ง แนะนำสำหรับเนื้อหาที่มีความสูงมากกว่าความกว้าง

หน้านี้แสดงวิธีใช้เลย์เอาต์แคโรเซลแบบหลายรายการและแบบไม่มีคอนเทนเนอร์ ดูข้อมูลเพิ่มเติมเกี่ยวกับประเภทเลย์เอาต์ได้ที่หลักเกณฑ์เกี่ยวกับภาพสไลด์ Material 3
พื้นผิว API
หากต้องการใช้แครูเซลแบบหลายการเรียกดูและแบบไม่มีคอนเทนเนอร์ ให้ใช้ Composable
HorizontalMultiBrowseCarousel
และ HorizontalUncontainedCarousel
Composable เหล่านี้มีพารามิเตอร์หลักต่อไปนี้ร่วมกัน
state
: อินสแตนซ์CarouselState
ที่จัดการดัชนีรายการปัจจุบันและ ตำแหน่งการเลื่อน สร้างสถานะนี้โดยใช้rememberCarouselState { itemCount }
โดยที่itemCount
คือจำนวนรายการทั้งหมดในภาพสไลด์itemSpacing
: กำหนดขนาดของพื้นที่ว่างระหว่างรายการที่อยู่ติดกันใน ภาพหมุนcontentPadding
: ใช้ระยะห่างรอบพื้นที่เนื้อหาของภาพหมุน ใช้ เพื่อเพิ่มพื้นที่ก่อนรายการแรกหรือหลังรายการสุดท้าย หรือเพื่อระบุ ขอบสำหรับรายการภายในภูมิภาคที่เลื่อนได้content
: ฟังก์ชันที่ประกอบกันได้ซึ่งรับดัชนีจำนวนเต็ม ใช้ Lambda นี้เพื่อกำหนด UI สำหรับแต่ละรายการในภาพหมุนตามดัชนีของรายการ
Composable เหล่านี้แตกต่างกันในวิธีที่ระบุการกำหนดขนาดรายการ
itemWidth
(สำหรับHorizontalUncontainedCarousel
): ระบุความกว้างที่แน่นอนสำหรับแต่ละรายการในภาพสไลด์ที่ไม่มีการจำกัดpreferredItemWidth
(สำหรับHorizontalMultiBrowseCarousel
): แนะนำความกว้างที่เหมาะสมสำหรับรายการในภาพสไลด์แบบหลายการเรียกดู ซึ่งช่วยให้คอมโพเนนต์แสดงหลายรายการได้หากมีพื้นที่
ตัวอย่าง: ภาพหมุนหลายหมวดหมู่
ข้อมูลโค้ดนี้จะใช้แคโรเซลแบบหลายการเรียกดู
@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 ) } }
ประเด็นสำคัญเกี่ยวกับโค้ด
- กำหนด
CarouselItem
คลาสข้อมูล ซึ่งจัดโครงสร้างข้อมูลสำหรับแต่ละองค์ประกอบในภาพสไลด์ - สร้างและจดจำ
List
ของCarouselItem
ออบเจ็กต์ที่สร้างขึ้นด้วยแหล่งข้อมูลรูปภาพและคำอธิบาย - ใช้
HorizontalMultiBrowseCarousel
ที่ประกอบได้ ซึ่งออกแบบมาเพื่อแสดงหลายรายการในภาพหมุน- ระบบจะเริ่มต้นสถานะของภาพสไลด์โดยใช้
rememberCarouselState
ซึ่งจะได้รับจำนวนรายการทั้งหมด - รายการมี
preferredItemWidth
(ในที่นี้คือ186.dp
) ซึ่งแนะนำความกว้างที่เหมาะสมสำหรับแต่ละรายการ โดยแคร์รอสเซลจะใช้ค่านี้เพื่อกำหนดจำนวนรายการที่แสดงบนหน้าจอได้พร้อมกัน - พารามิเตอร์
itemSpacing
จะเพิ่มช่องว่างเล็กๆ ระหว่างรายการ - Lambda ต่อท้ายของ
HorizontalMultiBrowseCarousel
จะวนซ้ำผ่านCarouselItems
ในแต่ละการวนซ้ำ ฟังก์ชันจะดึงข้อมูลรายการที่ดัชนีi
และแสดงผลImage
ที่ใช้ร่วมกันได้สำหรับรายการนั้น Modifier.maskClip(MaterialTheme.shapes.extraLarge)
จะใช้มาสก์รูปร่างที่กำหนดไว้ล่วงหน้ากับรูปภาพแต่ละรูปเพื่อให้มีมุมโค้งcontentDescription
ระบุคำอธิบายการช่วยเหลือพิเศษสำหรับรูปภาพ
- ระบบจะเริ่มต้นสถานะของภาพสไลด์โดยใช้
ผลลัพธ์
รูปภาพต่อไปนี้แสดงผลลัพธ์จากข้อมูลโค้ดก่อนหน้า

ตัวอย่าง: ภาพสไลด์แบบไม่จำกัด
ข้อมูลโค้ดต่อไปนี้จะใช้ภาพสไลด์ที่ไม่มีคอนเทนเนอร์
@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 ) } }
ประเด็นสำคัญเกี่ยวกับโค้ด
- Composable
HorizontalUncontainedCarousel
จะสร้างเลย์เอาต์ภาพสไลด์- พารามิเตอร์
itemWidth
จะกำหนดความกว้างคงที่สำหรับแต่ละรายการในภาพสไลด์
- พารามิเตอร์
ผลลัพธ์
รูปภาพต่อไปนี้แสดงผลลัพธ์จากข้อมูลโค้ดก่อนหน้า
