カルーセル

カルーセルには、ウィンドウ サイズに基づいて動的に調整されるアイテムのスクロール可能なリストが表示されます。カルーセルを使用して、関連するコンテンツのコレクションを紹介します。 カルーセル アイテムはビジュアルを重視していますが、アイテムのサイズに合わせて調整される短いテキストを含めることもできます。

さまざまなユースケースに対応できるよう、4 つのカルーセル レイアウトが用意されています。

  • マルチブラウズ: サイズの異なるアイテムが含まれます。写真など、多くのアイテムを一度に閲覧する場合におすすめです。
  • 非包含: 単一サイズのアイテムが含まれ、画面の端 を越えて流れます。各アイテムの上または下に、より多くのテキストやその他の UI を表示するようにカスタマイズできます。
  • ヒーロー: 1 つの大きな画像をハイライトして注目を集め、小さなアイテムで次のコンテンツを プレビューできます。映画や番組のサムネイルなど、強調したいコンテンツをスポットライトで照らす場合におすすめです。
  • 全画面: 端から端まで広がる大きなアイテムを一度に 1 つ表示し、 縦方向にスクロールします。高さが幅より長いコンテンツにおすすめです。
制約のない全画面カルーセル タイプが並んで表示されている。非包含型カルーセルには複数のカルーセル アイテムがあり、全画面表示型には画面全体を占める 1 つのアイテムがあります。
図 1.非包含（1）と全画面（2）のカルーセル タイプ。

このページでは、マルチブラウズと非包含のカルーセル レイアウトを実装する方法について説明します。レイアウト タイプの詳細については、カルーセルのマテリアル 3 ガイドラインを ご覧ください。

API サーフェス

マルチブラウズと非包含のカルーセルを実装するには、 HorizontalMultiBrowseCarousel と HorizontalUncontainedCarousel コンポーザブルを使用します。これらのコンポーザブルは、次の主要パラメータを共有します。

  • state: 現在のアイテム インデックスとスクロール位置を管理する CarouselState インスタンス。この状態は rememberCarouselState { itemCount } を使用して作成します。 ここで、itemCount はカルーセル内のアイテムの合計数です。
  • itemSpacing: カルーセル内の隣接するアイテム間の空白の量を定義します。
  • contentPadding: カルーセルのコンテンツ領域の周囲にパディングを適用します。これを使用して、最初のアイテムの前または最後のアイテムの後にスペースを追加したり、スクロール可能な領域内のアイテムにマージンを設定したりします。
  • content: 整数インデックスを受け取るコンポーズ可能な関数。このラムダを使用して、インデックスに基づいてカルーセル内の各アイテムの UI を定義します。

これらのコンポーザブルは、アイテムのサイズ指定方法が異なります。

  • itemWidth（HorizontalUncontainedCarousel の場合）: 非包含カルーセル内の各アイテムの正確な幅を指定します。
  • preferredItemWidth（HorizontalMultiBrowseCarousel の場合）: マルチブラウズ カルーセル内のアイテムの理想的な幅を示します。スペースがあれば、コンポーネントで複数のアイテムを表示できます。

例: マルチブラウズ カルーセル

次のスニペットは、マルチブラウズ カルーセルを実装しています。

コードに関する主なポイント

  • CarouselItem データクラスを定義します。このクラスは、カルーセル内の各要素のデータを構造化します。
  • 画像リソースと説明が入力された CarouselItem オブジェクトの List を作成して保存します。
  • カルーセルに複数のアイテムを表示するように設計された HorizontalMultiBrowseCarousel コンポーザブルを使用します。
    • カルーセルの状態は rememberCarouselState を使用して初期化されます。この関数には、アイテムの合計数が渡されます。
    • アイテムには preferredItemWidth（ここでは 186.dp）があり、各アイテムの最適な幅を示します。カルーセルはこれを使用して、一度に画面に収まるアイテムの数を決定します。
    • itemSpacing パラメータは、アイテム間に小さな間隔を追加します。
    • HorizontalMultiBrowseCarousel の末尾のラムダは、CarouselItems を反復処理します。各反復で、インデックス i のアイテムを取得し、 そのアイテムの Image コンポーザブルをレンダリングします。
    • Modifier.maskClip(MaterialTheme.shapes.extraLarge) は、定義済みのシェイプ マスクを各画像に適用し、角を丸くします。
    • contentDescription は、画像のアクセシビリティの説明を提供します。

結果

次の画像は、上記のスニペットの結果を示しています。

3 枚の画像を含むマルチブラウズ カルーセル。2 枚は完全に表示され、1 枚は画面の一部から外れています。
図 2.マルチブラウズ カルーセル。最後のアイテムが切り取られています。

例: 非包含カルーセル

次のスニペットは、非包含カルーセルを実装しています。

コードに関する主なポイント

  • HorizontalUncontainedCarousel コンポーザブルは、カルーセル レイアウトを作成します。
    • itemWidth パラメータは、カルーセル内の各アイテムの固定幅を設定します。

結果

次の画像は、上記のスニペットの結果を示しています。

3 つのアイテムを含む、コンテナなしのカルーセル。最後のアイテムは部分的に表示されますが、クリップされません。
図 3.非包含カルーセル。カルーセル内の最後のアイテムは切り取られていません。