Swiper配置选项、方法、函数详解笔录（二）

【前言】

   下面根据Swiper4的API文档，总结下Swiper的配置选项，包括全部配置选项、方法、函数

   本章内容会过长，根据内容列表查找相应配置选项即可快速找到

   注意：因为Swiper4的部分API存在BUG，所以这里我选择Swiper3的API讲解。若有Swiper4部分，我会加上提示

   紧接着上篇文章Swiper配置选项、方法、函数详解笔录（一）

 

【Swiper组件列表】

 （1）禁止切换

 （2）切换效果 

 （3）pagination分页器

 （4）前进后退按钮

 （5）滚动条

 （6）鼠标/键盘控制选项

 （7）图片选项

 （8）Zoom调焦

 （9）Controller双向控制

 （10）observer监听器

 （11）回调函数

 （12）移动端回调

 （13）Swiper属性

 （14）Swiper方法

 

【主体】

 （1）禁止切换     

    ①preventIntercationOnTransition（防止过渡时操作）  类型：boolean   默认：false   开始版本：Swiper4

若为true，则切换时滑动无效直到切换结束

    ②noSwiping（无滑动）                                                 类型：boolean        默认：true

设为true时，可以在slide上（或其他元素）增加类名'swiper-no-swiping'，使该slide无法拖动，希望文字被选中时可以考虑使用。该类名可通过noSwipingClass修改。

   案例：

   第二个slide上增加了类swiper-no-swiping，因此无法滑动（但是可以通过组件切换）

<div class="swiper-container">
	<div class="swiper-wrapper">
		<div class="swiper-slide">
			slider1</div>
		<div class="swiper-slide swiper-no-swiping">
			slider2</div>
		<div class="swiper-slide">
			slider3</div>
	</div>
</div>
<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
noSwiping : true,
})
</script>

   ③noSwipingSelector（无滑动选择器）         类型：string     注意：先开启noSwiping（无滑动）设置

设置不可触摸滑动的元素，例如input

   案例：表单无法滑动

<script type="text/javascript">
  var mySwiper = new Swiper('.swiper-container',{
    noSwiping: true,
    noSwipingSelector: 'input',
  });
</script>

    ④allowSlideNext（允许下张幻灯片）   类型：boolean   默认：true

设置为false可禁止向右或下滑动

   案例：锁定了向右滑动，按钮组件也失效了

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

   ⑤allowSlidePrev（允许上张幻灯片）     类型：boolean    默认：true

设为false可禁止向左或上滑动，用法与allowSlideNext（允许下张幻灯片）相同

   ⑥swipeHandler（处理器）                     类型：string/HTMLElement      默认：null

CSS选择器或者HTML元素。设置好后你只能拖动它进行swiping

     注意：swipeHandler设置在Swiper4 API暂时无效，所以这里我们用Swiper3 API来举例

<div class="swipe-handler">你只能拖动这里</div>
<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
swipeHandler : '.swipe-handler',
})
</script>

 

（2）切换效果    

      effect（效果）                 类型：string            默认：slide    启用版本：Swiper3.0.0

      slide的切换效果，默认为"slide"（位移切换），可设置为以下

      fade（淡入）；cube（方块）；coverflow（3d流）；flip（3d翻转）

<script language="javascript"> 
var mySwiper = new Swiper('#swiper-container',{
effect : 'fade淡入/cube方块/coverflow空间3D流/filp空间3D翻转',
})
</script>

 

（3）pagination分页器     

因为这里我用的Swiper4.0.0版本，所以这里分开总结下Swiper4与Swiper3相关API的操作

   ①pagination（分页）   类型：string or HTML Element     默认：null

分页器容器的css选择器或HTML标签。分页器等组件可以置于container之外，不同Swiper的组件应该有所区分，如#pagination1，#pagination2等

<div class="swiper-container">
    <div class="swiper-wrapper">
        <div class="swiper-slide">Slide 1</div>
        <div class="swiper-slide">Slide 2</div>
        <div class="swiper-slide">Slide 3</div>
    </div>
    <div class="swiper-pagination"></div>
</div>
<script language="javascript"> 
//以下为Swiper3的写法
var mySwiper = new Swiper('.swiper-container',{
     pagination : '.swiper-pagination',
     //pagination : '#swiper-pagination1',
})
//以下为Swiper4的写法
var mySwiper = new Swiper('.swiper-container',{
     pagination: {
         el: '.swiper-pagination',
     },
})
</script>

    ②el（分页配置）           类型：string or HTML Element     默认：null       开启版本：Swiper4.0.0

分页器容器的css选择器或HTML标签

//以下为Swiper4的写法
var mySwiper = new Swiper('.swiper-container',{
     pagination: {
         el: '.swiper-pagination',
     },
})

    ③paginationType（分页样式）   类型：string   默认：bullets圆点

分页器样式类型，可选。

    有四种类型：

    ‘bullets’  圆点（默认），‘fraction’  分式 ，‘progress’  进度条，‘custom’ 自定义

    ④paginationClickable（分页可点击）      类型：boolean      默认：false

此参数设置为true时，点击分页器的指示点分页器会控制Swiper切换

    ⑤paginationElement（分页标签）           类型：string          默认：span

设定分页器指示器（小点）的HTML标签

    ⑥paginationBulletRender分页小点渲染(index, className)   类型：function   默认：null

渲染分页器小点，这个参数允许完全自定义分页器的指示点，接受指示点索引和指示点类名作为参数

    Swiper4.0.0版本写法：

<style type="text/css">
    .swiper-pagination-bullet {
            width: 20px;
            height: 20px;
            text-align: center;
            line-height: 20px;
            font-size: 12px;
            color: #000;
            opacity: 1;
            background: rgba(0,0,0,0.2);
    }
    .swiper-pagination-bullet-active {
            color: #fff;
            background: #007aff;
    }
</style>
<script>
var swiper = new Swiper('.swiper-container', {
  pagination: '.swiper-pagination',
  paginationClickable: true,
  paginationBulletRender: function (swiper, index, className) {
      return '<span class="' + className + '">' + (index + 1) + '</span>';
  }
});  
</script>

    ⑦paginationFractionRender(分页分数呈现)        类型：function     默认：null

自定义分式类型分页器，当分页器类型设置为分式时可用

<script>
var swiper = new Swiper('.swiper-container', {
  pagination: '.swiper-pagination',
  paginationType : 'fraction',
  paginationFractionRender: function (swiper, currentClassName, totalClassName) {
      return '<span class="' + currentClassName + '"></span>' +
             ' of ' +
             '<span class="' + totalClassName + '"></span>';
  }
});
</script>

   ⑧paginationProgressRender(分页进度渲染)      类型：function     默认：null

自定义进度条类型分页器，当分页器类型设置为进度条时可用

<script>
var swiper = new Swiper('.swiper-container', {
 pagination: '.swiper-pagination',
  paginationType : 'progress',
  paginationProgressRender: function (swiper, progressbarClass) {
      return '<span class="' + progressbarClass + '"></span>';
   }
});
</script>

   ⑨uniqueNavElements（独立分页元素）   类型：boolean   默认：true

独立分页元素，当启用（默认）并且分页元素的传入值为字符串时，swiper会优先查找子元素匹配这些元素；可应用于分页器，按钮和滚动条

默认为true时，仅本swiper的container内的分页器有效，设置为false后，container以外的分页器也生效了

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

 

（4）前进后退按钮

nextButton（前进按钮），prevButton（后退按钮）

   案例：Swiper4.0.0写法

<div class="swiper-button-prev"></div>
<div class="swiper-button-next"></div>
<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
})
</script>

 

（5）滚动条

包含API

①滚动条添加；

②隐藏；

③拖动滚动条；

④拖动滚动条时释放后slide自动贴合；

具体参考Swiper的API文档

 

（6）鼠标/键盘控制选项

键盘控制：

①<>方向键控制；

鼠标控制：

①鼠标滚轮控制；②鼠标滚轮控制切换方向；③鼠标轮在边缘释放，控制页面移动；④鼠标滚轮反向；

⑤鼠标灵敏度；

   【内容主体】

   ①keyboardControl（键盘控制）     类型：boolean       默认：false

是否开启键盘控制Swiper切换。设置为true时，能使用键盘方向键控制slide滑动

   ②mousewheelControl（鼠标滚轮控制）   类型：boolean   默认：false

是否开启鼠标控制Swiper切换。设置为true时，能使用鼠标滚轮控制slide滑动

   ③mousewheelForceToAxis（鼠标滚轴方向）  类型：boolean   默认：false

当值为true让鼠标滚轮控制横向；为false时基于纵向

   ④mousewheelReleaseOnEdges（鼠标轮在边缘释放）  类型：boolean    默认：false

如果开启这个参数，当Swiper处于边缘位置时（第一个或最后一个slide），Swiper释放鼠标滚轮事件，鼠标可以控制页面滚动

   ⑤mousewheelInvert（鼠标滚轮反向）  类型：boolean   默认：false

这个参数会使鼠标滚轮控制方向反转

   ⑥mousewheelSensitivity（鼠标灵敏度） 类型：number   默认：1

鼠标滚轮的灵敏度，值越大鼠标滚轮滚动时swiper位移越大

 

（7）图片选项

①强制加载所有图片；

②图片延迟加载，使preloadImages无效（lazyLoading设为true开启图片延迟加载）；

③延迟加载在上下页，设置为true允许将延迟加载应用到最接近的slide的图片（前一个和后一个slide）；

 

（8）Zoom调焦

①双击放大：焦距功能：双击slide会放大，并且在手机端可双指触摸缩放；

②最大缩放焦距（放大倍率）；

③最小缩放焦距（放大倍率）；

④zoomToggle（放大切换），是否允许双击缩放。设置为false，不允许双击缩放，只允许手机端触摸缩放

 

（9）Controller双向控制

 ①另外一个Swiper实例开始控制该Swiper；

 ②控制方向倒转；

 ③两个swiper的slide数量不一致时可用controlBy:'container'；

 

（10）observer监听器

 ①当改变swiper的样式（例如隐藏/显示）或者修改swiper的子元素时，自动初始化swiper；

 ②将observe应用于Swiper的父元素。当Swiper的父元素变化时，例如window.resize，Swiper更新

 

（11）回调函数

①初始化后执行onInit(swiper)；

②碰触到slider时执行onTouchStart(swiper, event)；

③手指触碰Swiper并滑动（手指）时执行onTouchMove(swiper, event)；

④在最后一页继续拖动，释放执行onTouchEnd(swiper, event)；

⑤slide开始过渡到另一个slide时执行onSlideChangeStart(swiper)；

⑥slide过渡到另一个slide，结束时执行onSlideChangeEnd(swiper)；

⑦所有内置图像加载完成后执行onImagesReady(swiper)；

⑧开始过渡动画时执行onSetTransition(swiper, transition)；

⑨设置wrapper的偏移量时执行onSetTranslate(swiper, translate)；

⑩如果你的初始化slide不是第一个(例initialSlide:2)或者设置了loop: true，那么初始化时会触发一次 ；

⑪过渡开始时触发，接受Swiper实例作为参数。onTransitionStart（在转换开始）

   常结合动画使用，例如切换前消失

⑫过渡结束时触发，接收Swiper实例作为参数；

⑬手指触碰Swiper并拖动slide时执行，onSliderMove在滑块移动(swiper, event)；

⑭点击事件回调，当你点击或轻触Swiper 300ms后执行。onClick(swiper, event)

接受Swiper实例和touchend事件作为参数。可以对比移动端回调onTap()，可以对比本章(12)移动端回调

【触发时机】

如果没有触发onTouchMove，则释放触摸/鼠标时：

  1.立即执行onTap()

  2.如果触摸/鼠标按压时间小于300ms，并且两次触摸/点击间隔大于300ms，延迟300ms执行onClick

  3.如果触摸/鼠标按压时间小于300ms，并且两次触摸/点击间隔小于300ms，立即执行onDoubleTap

⑮两次轻触Swiper 时执行，类似于双击onDoubleTap(swiper, event)

⑯当Swiper的progress被改变时执行。接受Swiper实例和progress作为参数（可选）

   案例：获取progress并旋转slide

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
watchSlidesProgress : true,
onProgress: function(swiper, progress){
for (var i = 0; i < swiper.slides.length; i++){
var slide = swiper.slides[i];
es = slide.style;
es.webkitTransform = es.MsTransform = es.msTransform = es.MozTransform = 
es.OTransform = es.transform = 'rotate('+360*slide.progress+'deg)';
        }
      }
})
</script>

 ⑰切换到初始化位置时执行onReachBeginning()

 ⑱切换到最后一个Slide时执行onReachEnd(swiper)

⑲销毁Swiper时执行onDestroy(swiper)；

⑳自动切换开始时执行(由不自动切换进入到自动切换)；onAutoplayStart(swiper)；

21.自动切换结束时执行（由自动切换进入到不自动切换）；

22.图片延迟加载开始时执行。slide中每有一张图片被延迟加载就执行一次。接受Swiper实例

22.图片延迟加载结束时执行。slide中每有一张图片被延迟加载就执行一次。接受Swiper实例

23.滑块释放时如果触发slider向前(右、下)切换则执行。类似于onSlideChangeStart，但规定了方向。onSlideNextStart(swiper)

24.向前(右、下)切换结束时执行。类似于onSlideChangeEnd，但规定了方向。onSlideNextEnd(swiper)

25.滑块释放时如果触发slider向后(左、上)切换则执行。类似于onSlideChangeStart，但规定了方向。onSlidePrevStart(swiper)

26.向后(左、上)切换结束时执行；类似于onSlideChangeEnd，但规定了方向。onSlidePrevEnd(swiper)

27.生成分页器时执行onPaginationRendered(swiper, paginationContainer)

28.滚动鼠标滚轮控制slide跳转时执行onScroll(swiper, e)

29.在允许键盘控制状态下，按键盘时会触发这个函数onKeyPress

30.当swiper跟随windows变化尺寸时触发onBeforeResize(swiper)

31.当swiper跟随windows变化尺寸后触发onAfterResize(swiper)

 

（12）移动端回调

  ①当你轻触(tap)Swiper后执行。在移动端，click会有 200~300 ms延迟，所以请用tap代替click作为点击事件

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
onTap: function(swiper){
      alert('你tap了Swiper');
    }
})
</script>

 

（13）Swiper相关属性

  ①当前活动块(激活块)的索引，loop模式下注意该值会被加上复制的slide数（mySwiper.activeIndex）

var mySwiper = new Swiper('.swiper-container',{...})
$('#btn1').click(function(){
   alert(mySwiper.activeIndex); 
})

  ②当前活动块的索引，与activeIndex不同，在loop模式下不会将复制的块数量计在mySwiper.realIndex内

  ③返回活动块切换前的索引，注意是切换前的索引mySwiper.previousIndex

  ④获取swiper容器的宽度mySwiper.width

  ⑤获取swiper容器的高度mySwiper.height

  ⑥mySwiper.touches触碰相关属性，返回包含触控信息的对象数组，一共5个，包含开始触碰和结束触碰的位置及变化

  ⑦mySwiper.params重要参数，获取Swiper对象初始化参数，或者重写该参数，如： mySwiper.params.speed = 200。*不是所有参数都可以重写。

  应用：加快Swiper切换速度

  ⑧mySwiper.container容器属性

swiper的container的Dom7/jQuery对象。可以通过mySwiper.container[0]得到container的HTML元素。进而对Swiper进行修改

案例：把container的透明度减半

  ⑨mySwiper.wrapper外层包装

swiper的wrapper的Dom7/jQuery对象。可以通过mySwiper.wrapper[0]得到wrapper的HTML元素

案例：把wrapper的透明度减半

  ⑩mySwiper.slides幻灯片

获取Swiper的slides的Dom7/jQuery对象。可以通过mySwiper.slides[1]获取特定的slide，对其进行相关操作。

案例：提示slide数量并淡化第一个slide

  ⑪mySwiper.bullets分页导航点

获取Swiper的分页器的小点bullets的Dom7/jQuery对象。通过类似mySwiper.bullets[1]获取其中某个。

案例：第二个指示点加一像素白边

  ⑫获取wrapper的位移mySwiper.translate

  ⑬获取Swiper的progress值mySwiper.progress

      对于swiper的progress属性，活动的slide在最左（上）边时为0，活动的slide在最右（下）边时为1，其他情况平分。例：有6个slide，当活动的是第三个时swiper的progress属性是0.4，当活动的是第五个时swiper的progress属性是0.8

   ⑭判断Swiper是否在初始位置，如果Swiper位于最左/上，这个值为true（mySwiper.isBeginning）

   ⑮判断Swiper是否在结束位置，如果Swiper位于最右/下，这个值为true（mySwiper.isEnd）

   ⑯判断是否自动切换，如果Swiper开启了autoplay，这个值为true（mySwiper.autoplaying）

   ⑰判断Swiper是否正在过渡，如果Swiper正在过渡（自由滑动），这个值为true（mySwiper.animating）

   ⑱返回点击Slide的索引（mySwiper.clickedIndex）

//Swiper4.0.0写法
var mySwiper = new Swiper('.swiper-container',{
  onClick: function(swiper){
    alert(swiper.clickedIndex);
  }
})

    ⑲返回最后点击的Slide(HTML元素)，可以通过jQuery改变Slide样式（mySwiper.clickedSlide）

//Swiper4.0.0写法
var mySwiper = new Swiper('.swiper-container',{...})
$('#btn1').click(function(){
   mySwiper.clickedSlide.style.height='400px'; 
})

    ⑳后退按钮的Dom7/jQuery元素。可以通过mySwiper.prevButton[0]得到HTML元素（mySwiper.prevButton）

    21.前进按钮的Dom7/jQuery元素。可以通过mySwiper.nextButton[0]得到HTML元（mySwiper.nextButton）

   

（14）Swiper方法（Swiper4.0.0的API）

   ①滑动到下一个滑块mySwiper.slideNext(speed, runCallbacks)---单独上下页按钮

   ②滑动到前一个滑块mySwiper.slidePrev(speed,runCallbacks)---单独上下页按钮

   ③切换到指定slide，mySwiper.slideTo(index, speed, runCallbacks)---单独序列按钮

   ④销毁Swiper。销毁所有绑定的监听事件，移除鼠标键盘事件，释放浏览器内存mySwiper.destroy(deleteInstance, cleanupStyles)

   ⑤返回实时的wrapper位移mySwiper.getTranslate()

这与通过属性mySwiper.translate 获取到的数值稍有不同，即使是在过渡时（animating）也能获取到，而后者精度较高

   ⑥手动设置wrapper的位移mySwiper.setTranslate(translate)，translate必选，位移值（单位px）

   ⑦移除索引为index的slide，mySwiper.removeSlide(index)，例如：

mySwiper.removeSlide(0); //移除第一个
mySwiper.removeSlide([0, 1]); //移除第一个和第二个

   ⑧移除所有slides幻灯片，mySwiper.removeAllSlides()

   ⑨重新计算Swiper的尺寸，mySwiper.updateSize()

案例：增加第一个slide的高度后，需要更新，Swiper的高度才会变化

   ⑩重新计算Slides的数量，当你使用js来删除slide时可能会用到mySwiper.updateSlides()。

使用mySwiper.removeSlide来删除slide则会自动计算，无需使用此方法。

   ⑪重新计算Swiper的progress值，mySwiper.updateProgress()

   ⑫更新slides和bullets的active/prev/next 类名，对应分页点数等均更新mySwiper.updateSlidesClasses()

   ⑬更新Swiper，这个方法包含了updateContainerSize，updateSlidesSize，updateProgress，updateClasses方法mySwiper.update(updateTranslate)。

    可在删除Swiper后更新

   ⑭移除所有监听事件，包括点击拖动mySwiper.detachEvents()

   ⑮重新绑定所有监听事件mySwiper.attachEvents()

   ⑯添加slide到slides的结尾。可以是HTML元素或slide数组，mySwiper.appendSlide(slides)

   ⑰添加slide到slides的首位。可以是HTML元素或slide数组mySwiper.prependSlide(slides)

   ⑱添加回调函数或者事件句柄，这些事件只会执行N次mySwiper.on(callback,handler)

   ⑲添加回调函数或者事件句柄，这些事件只会执行一次mySwiper.once(callback,handler)

   ⑳移除某个回调/事件mySwiper.off(event, handler)

   21.开启鼠标的抓手形状。mySwiper.setGrabCursor()

   22.关闭鼠标的抓手形状mySwiper.unsetGrabCursor()

   23.移除事件句柄mySwiper.off(event)

 

 

 

 

 

 

 【总结】

（1）Swiper运作原理

Swiper常用运作方式有两种：手动触摸切换或者导航切换（前进后退按钮，键盘控制，分页器，内置方法slideTo等）

①手动触摸切换拖动阶段Swiper根据手势位置实时设定wrapper的位移（onSetTranslate），释放拖动时Swiper会设定一次wrapper自由过渡（onSetTranslate、onSetTransition、onTransitionStart、onSlideChangeStart）。速度为speed直到过渡结束（onTransitionEnd、onSlideChangeEnd）。

②导航切换可参考手动触摸释放阶段

 

 

 今天先总结到这里

.