カルーセルCarouselExperimental
スライドやカルーセル表示用のコンポーネントです。
プレビュー
状態とバリエーション
1枚表示
最初は1枚だけ見せ、前後ボタンやドットで1枚ずつ切り替える基本形です。
次のカードを少し見せる
現在のカードを主役にしつつ、次のカードだけを少し見せて横に続きがあることを伝えます。前後ボタンはカードに重ならない位置へ置きます。
表示領域に収めるカード
表示領域の中にカードだけを収める見せ方です。前後に余計なカードを見せず、現在のまとまりに集中させます。
表示枚数と送る枚数
2枚または3枚を同時に表示し、slidesToScroll で同じ枚数ずつ送ります。比較カードや商品一覧に向いています。
2枚表示 / 2枚送り
3枚表示 / 3枚送り
位置に応じたボタン表示
先頭では戻るボタン、末尾では次へボタンを隠します。スクロール位置に応じて必要な操作だけを表示します。
コントローラーの表示切り替え
標準的な前後ボタン、ドット、自動再生ボタンは controls prop で表示を切り替えられます。独自配置が必要な場合は個別コンポーネントを子要素として置きます。
前後ボタン + ドット
ドットのみ
コントローラーなし
画像カルーセル
画像を切り替える場合は、CarouselItem の中に ImagePreview を配置します。前後ボタン、ドット、現在位置を同じ Carousel 内で扱います。
ワークステーション
スタジオ
風景素材
左右の画像を100%幅で見せる
中央の表示領域は1枚分のまま、左右の画像も同じ100%幅で外側に見せます。左右ボタンとドットで移動でき、画像以外のカード型コンテンツにも応用できます。
ワークステーション
スタジオ
風景素材
画像サムネイルコントローラー
画像一覧ではドットだけでなくサムネイルで現在位置と移動先を確認できるようにします。CarouselThumbnail はクリックで該当スライドへ移動します。
ワークステーション
スタジオ
風景素材
自動再生とコントローラー
自動再生を使う場合は、停止と再開の操作を必ず用意します。ドットは現在位置の確認と直接移動に使います。
ワークステーション
スタジオ
風景素材
縦方向
縦方向に送るプレビューや短いステップ表示に使います。
プロパティ
| プロパティ | 型 | 初期値 | 説明 |
|---|---|---|---|
| opts | CarouselOptions | - | ループ、スナップ位置、送る枚数など、カルーセルの挙動を細かく調整するための高度な設定です。通常は GunjoUI の props と組み合わせて使います。 |
| plugins | CarouselPlugin | - | 内部エンジンの拡張が必要な場合に使う高度な拡張口です。通常の前後ボタン、ドット、自動再生は GunjoUI の props と子コンポーネントで扱います。 |
| orientation | "horizontal" | "vertical" | "horizontal" | スライド方向を横または縦に切り替えます。 |
| setApi | (api: CarouselApi) => void | - | Carousel API を外部から扱うためのコールバックです。 |
| autoPlay | boolean | false | 一定間隔で次のスライドへ送ります。停止操作が必要な場合は CarouselAutoplayToggle を併用します。 |
| autoPlayInterval | number | 4000 | 自動再生の間隔をミリ秒で指定します。 |
| pauseOnHover | boolean | true | ホバーまたはフォーカス時に自動再生を一時停止します。 |
| controls | boolean | CarouselControlOptions | false | 前後ボタン、ドット、自動再生ボタンなどの既定コントローラーを表示します。細かい配置や独自 UI が必要な場合は CarouselPrevious / CarouselNext / CarouselDots を子要素として配置します。 |
| viewportClassName | string | - | CarouselContent の表示領域に追加するクラスです。左右のスライドを見せる場合などに overflow を調整します。 |
| label | string | - | 前後ボタンの aria-label とツールチップに使う文言です。 |
| hideWhenDisabled | boolean | false | 前後ボタンが無効な位置ではボタン自体を非表示にします。 |
| index | number | - | CarouselThumbnail が移動するスライド位置です。 |