基础
initialSlide
WARNING
此配置仅在初始化swiper时使用,切勿与切换swiper的概念混淆。
默认情况下,z-swiper 初始化时会显示第一个 Slide。如果需要在初始化时显示其他特定的 Slide,可以通过指定初始索引来实现。
direction
WARNING
此配置需设置z-swiper
高度,或给父元素设置高度。
Swiper 的滑动方向可根据需求进行设置,支持水平方向切换(horizontal)和垂直方向切换(vertical),灵活适配不同场景。
enabled
Swiper 的初始启用状态。当 Swiper 被禁用时,它将隐藏所有导航元素,并且不会响应任何事件或交互。
WARNING
此配置只设置初始化状态。动态变更请使用 enable 和 disable 方法。
grabCursor
该选项为 Swiper 使用者提供了贴心的用户体验。当设置为 true 时,鼠标悬停在 Swiper 上时,指针会变成手掌形状;拖动时,指针则会变成抓手形状,提升操作的直观性和便捷性。
autoHeight
设置为 true 时,Slider 容器会自动适配当前激活幻灯片的高度。
cssMode Web-H5
WARNING
开启后,web-pc不支持拖动。web-h5可滑动。小程序和App暂不支持该配置。
开启此配置后,将由CSS Scroll Snap API
接管轮播。swiper中大多功能都不再支持,但在简单的轮播中,可以带来更好的性能。
height
WARNING
正常设置swiper高度请使用custom-style
。
单位为px
。如果需要设置rpx
,请通过uni.rpx2px()
转换后再传给swiper。
TIP
在 popup
中使用 swiper
时,小程序与 H5 的弹窗加载机制存在显著差异。在小程序环境中,即使弹窗尚未显示,其内容在页面加载后仍会被预加载。这种情况下,通过 uni.createSelectorQuery()
方法获取宽高会返回 null
。
为了应对这一问题,可以通过预设配置为 swiper
设置固定宽度,从而确保其正常显示和功能实现。
强制设置swiper容器的高度。仅在隐藏时初始化swiper时使用。
<z-swiper grabCursor :height="100">
<z-swiper-item v-for="item in list" :key="item.id">
<DemoItem :text="item.text"></DemoItem>
</z-swiper-item>
</z-swiper>
rewind
将此配置设置为 true 启用倒带模式。
启用后,在最后一个幻灯片上点击“下一步”导航按钮(或调用 .slideNext())将滑动回第一个幻灯片。 在第一个幻灯片上点击“上一步”导航按钮(或调用 .slidePrev())将滑动到最后一个幻灯片。
WARNING
不可与loop
同时使用。
speed
切换速度是指 Slider 自动滑动从开始到结束所需的时间(单位:ms),同时也指触摸滑动释放后到与目标位置贴合所用的时间。
width
WARNING
正常设置swiper宽度请使用custom-style
。
单位为px
。如果需要设置rpx
,请通过uni.rpx2px()
转换后再传给swiper。
TIP
在 popup
中使用 swiper
时,小程序与 H5 的弹窗加载机制存在显著差异。在小程序环境中,即使弹窗尚未显示,其内容在页面加载后仍会被预加载。这种情况下,通过 uni.createSelectorQuery()
方法获取宽高会返回 null
。
为了应对这一问题,可以通过预设配置为 swiper
设置固定宽度,从而确保其正常显示和功能实现。
强制设置swiper容器的宽度。仅在隐藏时初始化swiper时使用。
<z-swiper grabCursor :width="100">
<z-swiper-item v-for="item in list" :key="item.id">
<DemoItem :text="item.text"></DemoItem>
</z-swiper-item>
</z-swiper>
modules
TIP
所有模块modules
功能都需要通过此参数配置。
WARNING
v3版本不再默认引入所有modules
,这意味着在使用modules中的模块时,都需要手动引入。
同时部分modules
的css
也需手动引入。需要注意的是,将style
设置为scoped
会导致样式失效。推荐全局引入所需要的模块样式。参考:引入样式
具体可查看模块化按需引入
<z-swiper grabCursor autoplay :modules="[AutoPlay]">
<z-swiper-item v-for="item in list" :key="item.id">
<DemoItem :text="item.text"></DemoItem>
</z-swiper-item>
</z-swiper>
nested web
当存在嵌套swiper时,设置子swiper的nested为true后,滑动子swiper将不影响父swiper的滑动。