輪轉介面

輪轉介面會顯示可捲動的項目清單，並根據視窗大小動態調整。使用輪轉介面展示一系列相關內容。輪轉介面項目著重於視覺效果，但也可以包含簡短文字，並根據項目大小調整。

我們提供四種輪轉介面版面配置，可滿足不同用途：

• 多重瀏覽：包含不同大小的項目。建議用於一次瀏覽多個項目，例如相片。
• 無限制：包含單一大小的項目，且會超出螢幕邊緣。可自訂在每個項目上方或下方顯示更多文字或其他 UI。
• 主頁橫幅：醒目顯示一張大型圖片，並提供小型項目，讓使用者預覽下一個項目。建議用於突顯想強調的內容，例如電影或節目縮圖。
• 全螢幕：一次顯示一個無邊框大型項目，並垂直捲動。建議用於高度大於寬度的內容。

圖 1. 無邊框 (1) 和全螢幕 (2) 輪轉介面類型。

本頁說明如何實作多重瀏覽和無邊界輪轉介面版面配置。如要進一步瞭解版面配置類型，請參閱輪轉介面 Material 3 指南。

API 介面

如要實作多重瀏覽和無容器輪轉介面，請使用 HorizontalMultiBrowseCarousel 和 HorizontalUncontainedCarousel 可組合項。這些可組合項共用下列重要參數：

• state：管理目前項目索引和捲動位置的 CarouselState 執行個體。使用 rememberCarouselState { itemCount } 建立這個狀態，其中 itemCount 是輪轉介面中的項目總數。
• itemSpacing：定義輪轉介面中相鄰項目之間的空白空間大小。
• contentPadding：在輪轉介面的內容區域周圍套用邊框間距。您可以使用這個屬性，在第一個項目之前或最後一個項目之後新增空間，或為可捲動區域內的項目提供邊界。
• content：接收整數索引的可組合函式。使用這個 lambda，根據索引定義輪轉介面中每個項目的 UI。

這些可組合項目的差異在於指定項目大小的方式：

• 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
        )
    }
}
Carousel.kt

程式碼重點

• 定義 CarouselItem 資料類別，為輪轉介面中的每個元素建構資料。
• 建立並記住 CarouselItem 物件的 List，其中填入圖片資源和說明。
• 使用 HorizontalMultiBrowseCarousel 可組合項，專門用於在輪轉介面中顯示多個項目。
  • 輪轉介面的狀態會使用 rememberCarouselState 初始化，並提供項目總數。
  • 項目具有 preferredItemWidth (此處為 186.dp)，可建議每個項目的最佳寬度。輪轉介面會根據這項資訊，判斷畫面上一次可容納多少項目。
  • itemSpacing 參數會在項目之間加入小間距。
  • HorizontalMultiBrowseCarousel 的結尾 lambda 會疊代 CarouselItems。在每次疊代中，系統會擷取索引 i 處的項目，並為其算繪 Image 可組合項。
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) 會對每張圖片套用預先定義的形狀遮罩，使其呈現圓角。
  • contentDescription 提供圖片的無障礙說明。

結果

下圖顯示上述程式碼片段的結果：

圖 2. 多重瀏覽輪轉介面，最後一個項目遭到裁剪。

範例：無容器輪轉介面

以下程式碼片段會實作無容器輪轉介面：

@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

程式碼重點

• HorizontalUncontainedCarousel 可組合函式會建立輪轉介面版面配置。
  • itemWidth 參數會為輪轉介面中的每個項目設定固定寬度。

結果

下圖顯示上述程式碼片段的結果：

圖 3. 無容器輪轉介面，輪轉介面中的最後一個項目不會遭到裁剪。