【前言】
下面根据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)。
②导航切换可参考手动触摸释放阶段
今天先总结到这里
.