spz-carousel 轮播图

支持布局: container responsive intrinsic fill fixed fixed-height flex-item

何时使用

常用于一组图片的轮播。
当想要自动循环播放多张图片时，可以使用轮播图进行展示。

代码演示

基本用法

最简单的用法。

<spz-carousel layout="responsive" width="640" height="427" controls>
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

自定义按钮图标

使用带有 pre 属性的子元素来替换切换上一张按钮的图标。
使用带有 next 属性的子元素来替换切换下一张按钮的图标。

<spz-carousel layout="responsive" width="640" height="427" controls loop>
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>

  <svg pre xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24"><path d="M13.1714 12.0007L8.22168 7.05093L9.63589 5.63672L15.9999 12.0007L9.63589 18.3646L8.22168 16.9504L13.1714 12.0007Z" fill="#fff"></path></svg>
  <svg next xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24"><path d="M13.1714 12.0007L8.22168 7.05093L9.63589 5.63672L15.9999 12.0007L9.63589 18.3646L8.22168 16.9504L13.1714 12.0007Z" fill="#fff"></path></svg>
</spz-carousel>

自动切换

定时自动切换下一张，默认支持循环播放（尽管没有配置 loop 属性）。

<spz-carousel layout="responsive" width="640" height="427" autoplay delay="2000">
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

渐显效果

切换效果为渐显。

<spz-carousel layout="responsive" width="640" height="427" controls loop effect="fade" animate-time="1000">
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

高度自适应

切换时自适应不同幻灯的高度。

<spz-carousel layout="container" controls loop effect="fade" animate-time="800" auto-height>
  <spz-img src="https://img.staticdj.com/969d7faa33893c0cd941900ac3abc4ba.webp" alt="White rose" layout="responsive" width="640" height="960" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/546292026322dcd1060dc9fdfc42c9ca.jpg" alt="Flower" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

同时展示多张幻灯

同时可见1.2张幻灯。

<spz-carousel layout="responsive" width="640" height="427" loop visible-count="1.2">
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

全屏放大模式

点击幻灯，进入全屏放大模式。

<spz-carousel layout="responsive" width="640" height="427" loop zoom>
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

滚动条模式

原生的滚动方式，像滑动页面一样切换。

<spz-carousel layout="responsive" width="640" height="427" effect="swipe">
  <spz-img src="https://img.staticdj.com/e858445e80fa04320cff7fd6473335d2.webp" alt="Pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/7b45d0021c8955d7a38334a4b6a92609.webp" alt="Full pink rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
  <spz-img src="https://img.staticdj.com/0c67bf474af38d7abefb6c5da5dd6770.webp" alt="Red rose" layout="responsive" width="640" height="427" object-fit="cover"></spz-img>
</spz-carousel>

属性

属性名	说明	类型	默认值	是否必须
initial-slide	默认展示第几张幻灯	number	`0`	否
advance-count	同时可见和切换幻灯的数量, 支持媒体查询的写法，例如：`(min-width:960px) 2, 1`	number	`1`	否
visible-count	当前可见幻灯的数量，一次只能切换一张幻灯，支持媒体查询的写法，例如：`(min-width:960px) 2, 1`；支持小数，例如：`1.8`	number	`1`	否
zoom	如果该属性存在，点击幻灯进入全屏放大模式	-	-	否
controls	如果该属性存在，显示左右切换按钮	-	-	否
loop	如果该属性存在，轮播图支持循环	-	-	否
autoplay	如果该属性存在，幻灯开启自动切换	-	-	否
delay	自动切换延时，最小值：`1000`，单位：毫秒	number	`5000`	否
animate-time	切换动画时间，单位：毫秒	number	`300`	否
effect	切换动画效果，可选：`fade` \| `scroller` \| `swipe`	string	`scroller`	否
direct	水平或垂直方向，可选：`horizontal` \| `vertical`	string	`horizontal`	否
scroll-ratio	滑动一张幻灯宽度乘以该数值的距离才触发切换下一张的动作，取值范围 `0-1`	number	`0.01`	否
auto-height	如果该属性存在，幻灯的高度不一致时，切换会有动画效果	-	-	否
zoom-in	当幻灯进入全屏放大模式时，根元素会自动添加该属性	-	-	-
dragging	当处于手动拖动轮播节点时会自动添加该属性	-	-	-
dom-mounted	当子元素的节点初始化完毕后，容器自动添加该属性	-	-	-
pause	当设置此属性时，自动播放的轮播会暂停，直至移除此属性	-	-	否

幻灯容器属性

属性名	说明	类型
select	当前展示的幻灯索引，从 `0` 开始	number

方法

goToSlide

切换到指定的幻灯。

参数	说明	类型	是否必需
path	幻灯的 `src`	string	是，除非有 `index` 参数
index	幻灯的索引，从 `0` 开始	string	是，除非有 `path` 参数
animate	切换是否带动画效果	boolean	否

updateDirect

更新轮播图的 direct 属性。

参数	说明	类型	是否必需
direct	可同时切换幻灯的数量	number	是

updateCount

更新轮播图的 advance-count 属性。

参数	说明	类型	是否必需
count	水平或垂直方向，可选：`horizontal` \| `vertical`	string	是

goPrev

切换到上一张幻灯，不需要参数。

goNext

切换到下一张幻灯，不需要参数。

calcPosition

重新计算切换按钮的位置，必须配置 controls 属性，才生效，不需要参数。

事件

event 对象数据

属性	说明	类型
total	幻灯的总数	number
index	当前是第几张幻灯，索引默认从0开始	number
isImage	幻灯的类型，如果是图片，返回`true`	boolean
tagName	幻灯的标签名称，例如：`DIV`	string
path	幻灯的`src`属性	string \| null

mounted

当轮播图挂载完成时该事件会自动触发。

mediaChange

当调整页面匹配媒体查询的尺寸时，该事件会自动触发。支持的属性：advance-count, visible-count。

slideEnd

当切换幻灯动画完成时该事件会自动触发。

slideChange

当切换幻灯动画进行中时该事件会自动触发。

zoomIn

当幻灯进入全屏放大模式时该事件会自动触发。

zoomOut

当幻灯退出全屏放大模式时该事件会自动触发。

AI 摘要（LLM Ready）

组件标识：spz-carousel
用途一句话：用于展示多张图片、视频等内容的循环播放，支持自动播放或用户手动切换。
可识别属性条目：18
可识别方法小节：6
可识别事件小节：7
关键属性名（Top）：initial-slide、advance-count、visible-count、zoom、controls、loop
关键方法名（Top）：goToSlide、updateDirect、updateCount、goPrev、goNext、calcPosition
关键事件名（Top）：mounted、mediaChange、slideEnd、slideChange、zoomIn
阅读顺序建议：先看「何时使用」与「代码演示」，再核对属性/方法/事件。
关联文档：/guide/actions-and-events/ 、/guide/layouts/

spz-carousel 轮播图#

#何时使用

#代码演示

#基本用法

#自定义按钮图标

#自动切换

#渐显效果

#高度自适应

#同时展示多张幻灯

#全屏放大模式

#滚动条模式

#属性

#方法

#goToSlide

#updateDirect

#updateCount

#goPrev

#goNext

#calcPosition

#事件

#event 对象数据