輪轉介面

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

我們提供四種輪轉介面配置，可因應不同用途：

  • 多重瀏覽：包含不同大小的項目。建議用於一次瀏覽多個項目，例如相片。
  • 未包含：包含單一大小的項目，且會溢出螢幕邊緣。可自訂在每個項目上方或下方顯示更多文字或其他 UI。
  • 主要：醒目顯示一張大圖片，並透過小項目預覽下一個內容。建議用於強調顯示的內容，例如電影或節目縮圖。
  • 全螢幕：一次顯示一個從螢幕邊緣到邊緣的大型項目，並垂直捲動。建議用於高大於寬的內容。
並排顯示無容器和全螢幕輪播類型。未含容器的輪轉介面類型有多個輪轉介面項目，而全螢幕類型則有一個項目占據整個畫面
圖 1. 無容器 (1) 和全螢幕 (2) 輪播類型。

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

API 介面

如要實作多重瀏覽和無容器輪播，請使用 HorizontalMultiBrowseCarousel 和 HorizontalUncontainedCarousel 可組合函式。這些可組合函式共用下列主要參數：

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

這些可組合函式指定項目大小的方式有所不同：

  • itemWidth (適用於 HorizontalUncontainedCarousel)：指定未設限輪播中每個項目的確切寬度。
  • preferredItemWidth (適用於 HorizontalMultiBrowseCarousel)：建議多重瀏覽輪轉介面中項目的理想寬度，讓元件在空間允許的情況下顯示多個項目。

範例：多瀏覽輪轉介面

這個程式碼片段會實作多重瀏覽輪轉介面：

程式碼重點

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

結果

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

多重瀏覽輪轉介面，顯示 3 張圖片，其中兩張完整顯示，一張部分超出螢幕。
圖 2. 多重瀏覽輪轉介面，最後一個項目已剪輯。

範例：未包含的輪轉介面

以下程式碼片段會實作未包含的輪轉介面：

程式碼重點

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

結果

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

含有 3 個項目的無容器輪轉介面。最後一個項目會部分顯示，但不會遭到裁剪。
圖 3. 未受限的輪轉介面，輪轉介面中的最後一個項目不會遭到裁剪。