spz-carousel 轮播图

用于展示多张图片、视频等内容的循环播放，支持自动播放或用户手动切换。

布局

何时使用

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

代码演示

基本用法

最简单的用法。

<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>

属性

属性名	说明	类型	默认值	是否必须
initial-slide	默认展示第几张幻灯	number	`0`	否
advance-count	同时可见和切换幻灯的数量	number	`1`	否
visible-count	当前可见幻灯的数量，一次只能切换一张幻灯，支持小数，例如：`1.8`	number	`1`	否
zoom	如果该属性存在，点击幻灯进入全屏放大模式	-	-	否
controls	如果该属性存在，显示左右切换按钮	-	-	否
loop	如果该属性存在，轮播图支持循环	-	-	否
autoplay	如果该属性存在，幻灯开启自动切换	-	-	否
delay	自动切换延时，单位：毫秒	number	`5000`	否
animate-time	切换动画时间，单位：毫秒	number	`300`	否
effect	切换动画效果，可选：`fade` \| `scroller`	string	`scroller`	否
direct	水平或垂直方向，可选：`horizontal` \| `vertical`	string	`horizontal`	否
scroll-ratio	滑动一张幻灯宽度乘以该数值的距离才触发切换下一张的动作，取值范围 `0-1`	number	`0.01`	否
auto-height	如果该属性存在，幻灯的高度不一致时，切换会有动画效果	-	-	否
zoom-in	当幻灯进入全屏放大模式时，根元素会自动添加该属性	-	-	-

幻灯容器属性

属性名	说明	类型
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

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