Skip to content

基础

initialSlide

WARNING

此配置仅在初始化swiper时使用,切勿与切换swiper的概念混淆。

默认情况下,z-swiper 初始化时会显示第一个 Slide。如果需要在初始化时显示其他特定的 Slide,可以通过指定初始索引来实现。

类型
Number
默认值
0

direction

WARNING

此配置需设置z-swiper高度,或给父元素设置高度。

Swiper 的滑动方向可根据需求进行设置,支持水平方向切换(horizontal)和垂直方向切换(vertical),灵活适配不同场景。

类型
String
默认值
horizontal
可选项
horizontal
vertical

enabled

Swiper 的初始启用状态。当 Swiper 被禁用时,它将隐藏所有导航元素,并且不会响应任何事件或交互。

WARNING

此配置只设置初始化状态。动态变更请使用 enable 和 disable 方法。

类型
Boolean
默认值
true

grabCursor

该选项为 Swiper 使用者提供了贴心的用户体验。当设置为 true 时,鼠标悬停在 Swiper 上时,指针会变成手掌形状;拖动时,指针则会变成抓手形状,提升操作的直观性和便捷性。

类型
Boolean
默认值
false

autoHeight

设置为 true 时,Slider 容器会自动适配当前激活幻灯片的高度。

类型
Boolean
默认值
false

cssMode Web-H5

WARNING

开启后,web-pc不支持拖动。web-h5可滑动。小程序和App暂不支持该配置。

开启此配置后,将由CSS Scroll Snap API接管轮播。swiper中大多功能都不再支持,但在简单的轮播中,可以带来更好的性能。

类型
Boolean
默认值
false

height

WARNING

正常设置swiper高度请使用custom-style

单位为px。如果需要设置rpx,请通过uni.rpx2px()转换后再传给swiper。

TIP

popup 中使用 swiper 时,小程序与 H5 的弹窗加载机制存在显著差异。在小程序环境中,即使弹窗尚未显示,其内容在页面加载后仍会被预加载。这种情况下,通过 uni.createSelectorQuery() 方法获取宽高会返回 null

为了应对这一问题,可以通过预设配置为 swiper 设置固定宽度,从而确保其正常显示和功能实现。

强制设置swiper容器的高度。仅在隐藏时初始化swiper时使用。

类型
Number
默认值
-
html
<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同时使用。

类型
Boolean
默认值
false

speed

切换速度是指 Slider 自动滑动从开始到结束所需的时间(单位:ms),同时也指触摸滑动释放后到与目标位置贴合所用的时间。

类型
Number
默认值
300

width

WARNING

正常设置swiper宽度请使用custom-style

单位为px。如果需要设置rpx,请通过uni.rpx2px()转换后再传给swiper。

TIP

popup 中使用 swiper 时,小程序与 H5 的弹窗加载机制存在显著差异。在小程序环境中,即使弹窗尚未显示,其内容在页面加载后仍会被预加载。这种情况下,通过 uni.createSelectorQuery() 方法获取宽高会返回 null

为了应对这一问题,可以通过预设配置为 swiper 设置固定宽度,从而确保其正常显示和功能实现。

强制设置swiper容器的宽度。仅在隐藏时初始化swiper时使用。

类型
Number
默认值
-
html
<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中的模块时,都需要手动引入。

同时部分modulescss也需手动引入。需要注意的是,将style设置为scoped会导致样式失效。推荐全局引入所需要的模块样式。参考:引入样式

具体可查看模块化按需引入

类型
Array
默认值
-
html
<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的滑动。

类型
boolean
默认值
false

Released under the MIT License.