QiuYe UI
内容与媒体

Carousel

通用轮播图，手感对标 iOS 分页滚动：拖拽与触摸 1:1 跟手、纵向滑动交还页面，两端橡皮筋阻尼，松手按速度投影吸附并可中途接住；支持不复制节点的无限循环、每屏多张与断点、居中 / 起始对齐、按张 / 按页吸附与自由惯性滚动、渐隐与中心缩放、图片视差与自动高度；内置悬停箭头、随拖动连续变形并显示自动播放进度的指示点、分数指示、触控板与键盘；配套 CarouselImage 提供 cover / contain（模糊衬底）、懒加载与骨架。

轮播图carousel滑动拖拽橡皮筋自动播放图片画廊无限循环

快速预览

查看 Carousel 组件的基本效果

跟手拖拽

1:1 跟随指针，拉过两端是越拉越沉的橡皮筋

第 1 张，共 5 张

基本用法

使用 Carousel 组件的基础示例

导入组件

1import {
2  Carousel,
3  CarouselContent,
4  CarouselImage,
5} from "@/components/qiuye-ui/carousel";

使用组件

1<Carousel loop autoplay parallax={0.2}>
2  <CarouselContent className="aspect-video rounded-2xl">
3    {banners.map((banner) => (
4      <CarouselImage key={banner.id} src={banner.src} alt={banner.alt} overlay>
5        <h3 className="p-6 pb-12 text-2xl font-semibold">{banner.title}</h3>
6      </CarouselImage>
7    ))}
8  </CarouselContent>
9</Carousel>

组件演示

查看组件的各种使用方式和效果

横幅大图
循环 + 自动播放 + 视差：拖动或甩动切换，图片反向轻移带出景深；指针移入时暂停并显示两侧箭头，活动指示点里是播放进度。
云海之上
风光

云海之上

黄昏时分，群峰浮出云层

第 1 张，共 5 张
卡片货架
按视口宽度配置每屏张数（窄屏 1.15 张露出下一张），按页吸附；箭头放在标题右侧，指示点在视口下方。

旅行灵感

窄屏露出下一张，宽屏每屏 2–3 张

晨雾山谷

晨雾山谷

苏格兰高地

5 天
第 1 张，共 8 张
中心聚焦
居中对齐 + effect="scale"：两侧的幻灯片缩小变暗，点击两侧即可切换过去。
梦莲湖

梦莲湖

第 1 张，共 7 张
商品图集
contain + 模糊衬底完整显示不同比例的照片，右上角是分数指示器，下方缩略图条与当前张联动。
无线头戴耳机
第 1 张，共 6 张

无线头戴耳机

¥ 1,299

照片宽高比各不相同：fit="contain" 完整显示，留白处铺一层同图的大模糊衬底。缩略图条用 useCarousel() 读取当前张，高亮框跟随拖动连续移动。

第 1 张，共 6 张
推荐语
effect="fade" + crossFade：纯文字幻灯片先淡出再淡入；autoHeight 让视口高度随文字长度连续过渡（拖动时同样连续）。
拖动时它真的跟着手指走，松手后的那一下弹簧，和 iPhone 上翻页几乎一样。
林晓iOS 工程师
第 1 张，共 5 张
自由滚动
slidesPerView="auto" 按内容宽度排布，snap="none" 松手后按 UIScrollView 的减速率惯性滑行，两端回弹；视口外的标签也能用 Tab 聚焦，聚焦时自动滚入视野。
腕表
腕表
运动鞋
运动鞋
墨镜
墨镜
日常
日常
耳机
耳机
相机
相机
香水
香水
跑鞋
跑鞋
眼镜
眼镜
参数调试
实时调整参数观察效果；拖动、甩动、拉过两端，或用触控板横向滑动、方向键切换。
第 1 张

1

第 1 张，共 8 张

布局

每屏张数 slidesPerView1
间距 gap12px
幻灯片数量8

效果与导航

视差 parallax0.20

行为

播放间隔 delay4000ms