Swiper4.x的全部配置选项、方法、函数，具体使用

最新推荐文章于 2024-10-11 11:41:44 发布

极地雪狼li

最新推荐文章于 2024-10-11 11:41:44 发布

阅读量5.3k

点赞数

分类专栏： swiper js web前端文章标签： swiper js web前端 api

web前端同时被 3 个专栏收录

53 篇文章 20 订阅

订阅专栏

43 篇文章 3 订阅

订阅专栏

swiper

3 篇文章 0 订阅

订阅专栏

一、Swiper4.x的全部配置选项、方法、函数

1.swiper一般选项

1.1initialSlide设定初始化时slide的索引。设置为1后，Swiper初始化时默认显示第2个轮播图

1.2direction设置Slides的滑动方向，可设置水平(horizontal)或垂直(vertical)。horizontal：横向切换，vertical：竖向切换。

1.3speed切换速度，即slider自动滑动开始到结束的时间（单位ms），也是触摸滑动时释放至贴合的时间。

1.4grabCursor设置为true时，鼠标覆盖Swiper时指针会变成手掌形状，拖动时指针会变成抓手形状。（根据浏览器形状有所不同）

1.5parallax设置为true开启视差效果。

效果可以应用于container或slide的子元素。当应用于container的子元素（常用于视差背景图），每次切换时视差效果仅有设定值的slide个数-1分之1

视差位移变化

在所需要的元素上增加data-swiper-parallax属性（与Swiper切换方向相同）或data-swiper-parallax-x （x方向） data-swiper-parallax-y（y方向）
data-swiper-parallax接受两种类型的参数。
number（单位：px），如-300，从右边300px进入左边出去。
percentage（百分比），移动距离=该元素宽度 * percentage。
视差透明度变化
在所需要的元素上增加data-swiper-parallax-opacity属性。可选值0-1，如0.5，从半透明进入半透明出去
视差缩放变化
在所需要的元素上增加data-swiper-parallax-scale属性。可选值如0.5，从一半大小进入一半大小出去
还可通过data-swiper-parallax-duration设定视差动画持续时间（ms）。默认值是Swiper的speed，与切换时间同步。

*设定透明度或缩放必须同时设定位移，否则无效(4.0.5) <div data-swiper-parallax="0" data-swiper-parallax-opacity="0.5" >透明度变化</div>

<div class="swiper-container">
<div style="background-image:url(/img/Parallax.jpg)" data-swiper-parallax="-23%" data-swiper-parallax-duration="3000"></div>
<div class="swiper-wrapper">
<div class="swiper-slide">
<div class="title" data-swiper-parallax="-100">从右边100px开始进入</div>
<div class="subtitle" data-swiper-parallax="-200">从右边200px开始进入</div>
<div class="text" data-swiper-parallax="-300" data-swiper-parallax-duration="600">
<p>从右边300px开始进入，时间600ms</p>
</div>
<div data-swiper-parallax="0" data-swiper-parallax-opacity="0.5" >透明度变化</div>
<div data-swiper-parallax-scale="0.15" >缩放变化</div>
</div>
</div>
</div>
<script language="javascript">
var mySwiper = new Swiper('.swiper-container',{
parallax : true,
})
</script>
<div data-swiper-parallax="0" data-swiper-parallax-opacity="0.5" >透明度变化</div>
<div data-swiper-parallax-scale="0.15" >缩放变化</div>
</div>
</div>
</div>
<script language="javascript">
var mySwiper = new Swiper('.swiper-container',{
parallax : true,
})
</script>

1.6setWrapperSize

Swiper使用flexbox布局(display: flex)，开启这个设定会在Wrapper上添加等于slides相加的宽或高，在对flexbox布局的支持不是很好的浏览器中可能需要用到。

1.7virtualTranslate
虚拟的位移。当你启用这个参数，Slide不会移动，但是Swiper还是在运行，例如progress，active-slide，各种回调等。当你想自定义一些slide切换效果时可以用。例如配合上progress。

启用这个选项时slideChange和transition等事件有效（与Swiper3.x不同）。可以用来使Swiper的滑动停止（锁定）。

1.8a11y
辅助，无障碍阅读。开启本参数为屏幕阅读器添加语音提示等信息，方便视觉障碍者。基于ARIA标准。
prevSlideMessage 类型：string 默认：'Previous slide' 在屏幕阅读器为上一页按钮添加信息。
nextSlideMessage 类型：string 默认： 'Next slide' 在屏幕阅读器为下一页按钮添加信息。
firstSlideMessage 类型：string 默认： 'This is the first slide' 在屏幕阅读器当处于第一个slide为上一页按钮添加信息。
lastSlideMessage 类型：string 默认： 'This is the last slide' 在屏幕阅读器当处于最后一个slide为下一页按钮添加信息。
paginationBulletMessage 类型：string 默认： 'Go to slide {{index}}' 在屏幕阅读器为分页器小点添加信息。

notificationClass 类型：string 默认：'swiper-notification' A11y公告部分的类名。

1.9width

强制Swiper的宽度(px)，当你的Swiper在隐藏状态下初始化时才用得上。这个参数会使自适应失效。

1.10height

强制Swiper的高度(px)，当你的Swiper在隐藏状态下初始化时且切换方向为垂直才用得上。这个参数会使自适应失效。

1.11roundLengths
设定为true将slide的宽和高取整(四舍五入)以防止某些分辨率的屏幕上文字或边界(border)模糊。

例如在1440宽度设备上，当你设定slide宽为76%时，则计算出来结果为1094.4，开启后宽度取整数1094。

1.12breakpoints
断点设定：根据屏幕宽度设置某参数为不同的值，类似于响应式布局的media screen。

只有部分不需要变换布局方式和逻辑结构的参数支持断点设定，如slidesPerView、slidesPerGroup、 spaceBetween，而像slidesPerColumn、loop、direction、effect等则无效。

1.13autoHeight

自动高度。设置为true时，wrapper和container会随着当前slide的高度而发生变化。

1.14uniqueNavElements
独立分页元素，当启用（默认）并且分页元素的传入值为字符串时，swiper会优先查找子元素匹配这些元素。可应用于分页器，按钮和滚动条（pagination, prev/next buttons and scrollbar elements）。

当你的控制组件放在container外面的时候，需要用到。

效果演示

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
  pagination: {
    el: '.swiper-pagination',
  },
  uniqueNavElements: false,
})
</script>

1.15nested
用于嵌套相同方向的swiper时，当切换到子swiper时停止父swiper的切换。
请将子swiper的nested设置为true。
由于需要在slideChangeEnd时判断作用块，因此快速滑动时这个选项无效。

1.16runCallbacksOnInit

如果你的初始化slide不是第一个(例initialSlide:2)或者设置了loop: true，那么初始化时会触发一次 [Transition/SlideChange] [Start/End] 回调函数，如果不想触发，设置为false。

1.17watchOverflow
当没有足够的slide切换时，例如只有1个slide（非loop），swiper会失效且隐藏导航等。默认不开启这个功能

<div class="swiper-container">
   <div class="swiper-wrapper">
       <div class="swiper-slide blue-slide">
           slider1</div>
   </div>
   <div class="swiper-pagination"></div>
   <div class="swiper-button-prev"></div>
   <div class="swiper-button-next"></div>
   <div class="swiper-scrollbar"></div>
</div>
<script>
var mySwiper = new Swiper('.swiper-container',{
watchOverflow: true,//因为仅有1个slide，swiper无效
navigation: {
nextEl: '.swiper-button-next',//自动隐藏
prevEl: '.swiper-button-prev',//自动隐藏
},
pagination: {
el: '.swiper-pagination',//自动隐藏
},
scrollbar: {
el: '.swiper-scrollbar',//自动隐藏
},
})
</script>

1.18on

注册事件，Swiper4.0开始使用关键词this指代Swiper实例。

1.20preloadImages
默认为true，Swiper会强制加载所有图片。

1.21updateOnImagesReady
当所有的内嵌图像（img标签）加载完成后Swiper会重新初始化。使用此选项需要先开启preloadImages: true

2.网格分布

2.1centeredSlides
设定为true时，active slide会居中，而不是默认状态下的居左。

2.2slidesPerView
设置slider容器能够同时显示的slides数量(carousel模式)。
可以设置为数字（可为小数，小数不可loop），或者 'auto'则自动根据slides的宽度来设定数量。
loop模式下如果设置为'auto'还需要设置另外一个参数loopedSlides。

2.3slidesPerGroup
在carousel mode下定义slides的数量多少为一组。

2.4spaceBetween
在slide之间设置距离（单位px）。

2.5slidesPerColumn
多行布局里面每列的slide数量。设置显示几行

2.6slidesPerColumnFill
多行布局中以什么形式填充：（数字代表第几张轮播图）
'column'（列）
1   3   5
2   4   6
'row'（行）。
1   2   3
4   5   6

2.7slidesOffsetBefore
设定slide与左边框的预设偏移量（单位px）。

2.8slidesOffsetAfter
设定slide与右边框的预设偏移量（单位px）。

2.9normalizeSlideIndex
使你的活动块指示为最左边的那个slide（没开启centeredSlides时）

3.LOOP环路

3.1loop
设置为true 则开启loop模式。loop模式：会在原本slide前后复制若干个slide(默认一个)并在合适的时候切换，让Swiper看起来是循环的。
loop模式在与free模式同用时会产生抖动，因为free模式下没有复制slide的时间点。

3.2loopAdditionalSlides
loop模式下会在slides前后复制若干个slide,，前后复制的个数不会大于原总个数。
默认为0，前后各复制1个。0,1,2 --> 2,0,1,2,0
例：取值为1，0,1,2 --> 1,2,0,1,2,0,1
例：取值为2或以上，0,1,2 --> 0,1,2,0,1,2,0,1,2

3.3loopedSlides
在loop模式下使用slidesPerview:'auto'，还需使用该参数设置所要用到的loop个数(一般设置为本来slide的个数)。

3.4loopFillGroupWithBlank
在loop模式下，为group填充空白slide

4.Clicks点击

4.1slideToClickedSlide
设置为true则点击slide会过渡到这个slide。

5.TOUCHES触发条件

5.1touchRatio
触摸比例。触摸距离与slide滑动距离的比率。设置为0.5后slide滑动距离只有触摸距离的一半，变得难以滑动。设置为-1后与拖动方向相反的Swiper

5.2simulateTouch
鼠标模拟手机触摸。默认为true，Swiper接受鼠标点击、拖动。电脑端移动无效

5.3allowTouchMove
允许触摸滑动。设为false时，slide无法滑动，只能使用扩展API函数例如slideNext() 或slidePrev()或slideTo()等改变slides滑动。
等同于Swiper3.x 的 onlyExternal

5.4followFinger
跟随手指。如设置为false，手指滑动时slide不会动，当你释放时slide才会切换。

5.5shortSwipes
默认允许短切换。设置为false时，只能长切换，进行快速且短距离的滑动无法触发切换。

5.6longSwipes
设置为false时，进行长时间长距离的拖动无法触发Swiper。
*某些版本无效(4.0.7)

5.7longSwipesMs
定义longSwipes的时间（单位ms），超过则属于longSwipes。

5.8longSwipesRatio
进行longSwipes时触发swiper所需要的最小拖动距离比例，即定义longSwipes距离比例。值越大触发Swiper所需距离越大。最大值0.5。

5.9threshold
拖动的临界值（单位为px），如果触摸距离小于该值滑块不会被拖动。

5.10resistance
边缘抵抗。当swiper已经处于第一个或最后一个slide时，继续拖动Swiper会离开边界，释放后弹回。边缘抵抗就是拖离边界时的抵抗力。值为false时禁用，将slide拖离边缘时完全没有抗力。

6.CALLBACKS回调函数

6.1init
回调函数，初始化后执行。

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
  on: {
    init: function(){
      //Swiper初始化了
      alert('当前的slide序号是'+this.activeIndex);
    }, 
  },
})
</script>

6.2touchStart(event)
回调函数，当碰触到slider时执行。可选touchstart事件作为参数。

7.SWIPER方法

7.1mySwiper.slideNext(speed, runCallbacks)滑动到下一个滑块。mySwiper.slidePrev(speed,runCallbacks)
滑动到前一个滑块。speed：可选，切换速度runCallbacks：可选，设为false不触发transition回调函数