移动端触摸滑动插件Swiper

一、了解Swiper

目前移动端项目一般都需要具有触屏焦点图的效果，如果你也需要实现这一功能的话，Swiper是一个不错的选择。

1、他不需要加载任何公共库（如jQuery）即可运行，这保证了Swiper的轻量和运行速度。Swiper也可以在加载了公共库的环境下安全的动行，如jQuery，Zepto，jQuery Moblie等。

2、Swiper默认的触摸比例为1:1，你可以通过修改Swiper的设置来改变这个比例。

3、Swiper 增加了选项可以开启 Mutation Observer,有了这个功能Swiper可以在你动态改变Dom或Swiper的样式时自动重新初始化并计算所需的元素。

4、Swiper拥有丰富的API，他允许你建立自己独特的分页器、导航、视差滚动、或其他精彩的效果。

5、Swiper是唯一一个支持100%RTL布局的滑动插件。

6、Swiper允许多行Slides布局，这样每行的slide就会较少。

7、增加了三种新的过渡效果：淡入、3D方块、3D流。

8、现在Swiper可以用来控制其他的Swiper，甚至可以同时控制。

9、Swiper带有所有常用的导航控制器，包括分页器，切换箭头，滚动条。

10、Swiper使用流行的flexbox布局，这样就解决了很多计算尺寸方面的问题。这种布局也允许用CSS来设定Slides。

11、你可以在Swiper初始化的时候设定slide的显示，包括每行、每列、每组数量以及他们的间距等。

12、Swiper支持流行的视差滚动效果，这种效果可以应用在Swiper里任一元素上，图片、文本块、标题、背景等等。

13、Swiper懒加载延迟了不活动/不可见的图片加载，用户滑动时才加载他们。这一特性可以使页面加载更快并可提高Swiper的性能。

14、Swiper3还包含了所有swiper2的牛逼功能，包括自适应、滚动反弹、抵抗反弹、loop模式、嵌套Swiper。

二、使用方法

1.首先加载插件，Swiper准备了基础测试包供你使用，测试包里面已经包含了swiper.min.js和swiper.min.css文件。

<!DOCTYPE html><html><head>

…

…

如果你的页面加载了jQuery.js或者zepto.js，你可以选择使用更轻便的swiper.jquery.min.js。

<!DOCTYPE html><html><head>

…

…

2.HTML内容。

<div class=”swiper-slide”>Slide 1</div>

<div class=”swiper-slide”>Slide 2</div>

<div class=”swiper-slide”>Slide 3</div>

</div>

<!– 如果需要分页器 –>

<!– 如果需要导航按钮 –>

<!– 如果需要滚动条 –>

3.你可能想要给Swiper定义一个大小。

.swiper-container {

width: 600px;

height: 300px;}

4.初始化Swiper：最好是挨着</body>标签

var mySwiper = new Swiper (‘.swiper-container’, {

direction: ’vertical’,

loop: true,

// 如果需要分页器

pagination: ’.swiper-pagination’,

// 如果需要前进后退按钮

nextButton: ’.swiper-button-next’,

prevButton: ’.swiper-button-prev’,

// 如果需要滚动条

scrollbar: ’.swiper-scrollbar’,

})

</script></body>

如果不能写在HTML内容的后面，则需要在页面加载完成后再初始化。

window.onload = function() {

…

}

</script>

或者这样（Jquery和Zepto）

$(document).ready(function () {

…

})

</script>

三、API

Parameter	Type	Default	Description
initialSlide	number	0	初始slide的索引
direction	string	‘horizontal’	可以是’horizontal’或’vertical’(垂直滑动)
speed	number	300	滑动速度(单位ms)
setWrapperSize	boolean	false	开启这个设定会在Wrapper上添加等于slides相加的宽高，在对flexbox布局的支持不是很好的浏览器中可能需要用到。
virtualTranslate	boolean	false	虚拟位移。当你启用这个参数，Swiper除了不会移动外其他的都像平时一样运行，仅仅是不会在Wrapper上设置位移。当你想自定义一些slide切换效果时可以用。比如我们提供的cube切换效果，当slide切换时，Wrapper的位置是固定的。
Autoplay(自动切换)
autoplay	number	-	自动切换的时间间隔（单位ms），不设定该参数slide不会自动切换。
autoplayDisableOnInteraction	boolean	true	如果设置为false，用户操作swiper之后自动切换不会停止，每次都会重新启动autoplay。
Progress(进度)
watchSlidesProgress	boolean	false	开启这个参数来计算每个slide的progress(进展)
watchSlidesVisibility	boolean	false	必须先开启watchSlidesProgress 开启了watchSlidesVisibility，则会在每个可见slide增加一个classname
Freemode(free模式)
freeMode	boolean	false	设置为true时，将开启free模式，即滑动停止后停在当前位置，而不是当前帧的位置。
freeModeMomentum	boolean	true	设置为true时，滑动释放slide后仍会靠动量继续滑动，为false时，释放后立即停止。
freeModeMomentumRatio	number	1	设置的值越大，当释放slide时的滑动距离越大。
freeModeMomentumBounce	boolean	true	false时禁用free模式下的动量反弹，slides通过惯性滑动到边缘时，无法反弹。
freeModeMomentumBounceRatio	number	1	值越大产生的边界反弹效果越明显，反弹距离越大。
Effects(切换效果)
effect	string	‘slide’	可设置为”slide”（位移切换）”fade”（淡入）”cube”（方块）”coverflow”（3d流）。
fade	object	fade: { crossFade: false}	fade效果参数
cube	object	cube: { slideShadows: true, shadow: true, shadowOffset: 20, shadowScale: 0.94}	cube效果参数
coverflow	object	coverflow: { rotate: 50, stretch: 0, depth: 100, modifier: 1, slideShadows : true}	coverflow效果参数
Parallax(视差效果)
parallax	boolean	false	开启视差效果
Slides grid(网格分布)
spaceBetween	number	0	slide之间的距离（单位px）
slidesPerView	number or ‘auto’	1	设置slider容器能够同时显示的slides数量(carousel模式)。
slidesPerColumn	number	1	多行布局里面每列的slide数量。
slidesPerColumnFill	string	‘column’	多行布局中以什么形式填充’cloumn’和’row’
slidesPerGroup	number	1	在carousel mode下定义slides的数量多少为一组。
centeredSlides	boolean	false	设定为true时，活动块会居中，而不是默认状态下的居左。
Grab Cursor(抓手光标)
grabCursor	boolean	false	设置为true时，鼠标覆盖Swiper时指针会变成手掌形状，拖动时指针会变成抓手形状
Touches(触发)
touchRatio	number	1	触摸距离与slide滑动距离的比率。
touchAngle	number	45	允许触发拖动的角度值
simulateTouch	boolean	true	默认为true，Swiper接受鼠标点击、拖动
shortSwipes	boolean	true	设置为false时，进行快速短距离的拖动无法触发Swiper。
longSwipes	boolean	true	设置为false时，进行长时间长距离的拖动无法触发Swiper。
longSwipesRatio	number	0.5	进行longSwipes时触发swiper所需要的最小拖动距离比例，值越大触发Swiper所需距离越大。最大值0.5。
longSwipesMs	number	300	定义longSwipes的时间（单位ms），超过则属于longSwipes。
followFinger	boolean	true	如设置为false，拖动slide时它不会动，当你释放时slide才会切换。
onlyExternal	boolean	false	值为true时，slide无法拖动，只能使用扩展API函数来改变slides滑动。
threshold	number	0	拖动的临界值（单位为px），如果触摸距离小于该值滑块不会被拖动。
touchMoveStopPropagation	boolean	true	true时阻止touchmove冒泡事件。
Touch Resistance(触摸阻力)
resistance	boolean	true	值为false时将slide拖出边缘时完全没有抗力
resistanceRatio	number	0.85	抵抗率。resistant bounds（抵抗反弹）抵抗力的大小比例。值越小抵抗越大越难将slide拖出边缘。
Clicks(点击)
preventClicks	boolean	true	默认为true，当swiping时阻止意外的链接点击。
preventClicksPropagation	boolean	true	阻止click冒泡。拖动Swiper时阻止click事件。
slideToClickedSlide	boolean	false	设置为true则swiping时点击slide会过渡到这个slide。
Swiping / No swiping(禁止)
allowSwipeToPrev	boolean	true	设为false可禁止向左或上滑动。
allowSwipeToNext	boolean	true	设置为false可禁止向右或下滑动。
noSwiping	boolean	true	设为true时，可以在slide上增加类名’swiper-no-swiping’，使该slide无法滑动。
noSwipingClass	string	‘swiper-no-swiping’	不可拖动块的类名，当noSwiping设置为true时，并且在slide加上此类名，slide无法拖动。
swipeHandler	string / HTMLElement	null	CSS选择器或者HTML元素。你只能拖动它进行swiping。
Pagination(分页器)
pagination	string / HTMLElement	null	分页器容器的css选择器或HTML标签。
paginationHide	boolean	true	true时点击Swiper的container会显示/隐藏分页器。
paginationClickable	boolean	false	值为true时，点击分页器的指示点时会发生Swiper。
paginationBulletRender(index, className)	function	null	渲染分页器小点。这个参数允许完全自定义分页器的指示点。
Navigation Buttons(前进后退按钮)
nextButton	string / HTMLElement	null	前进按钮的css选择器或HTML元素。
prevButton	string / HTMLElement	null	后退按钮的css选择器或HTML元素。
Scollbar(滚动条)
scrollbar	string / HTMLElement	null	Scrollbar容器的css选择器或HTML元素。
scrollbarHide	boolean	true	滚动条是否自动隐藏。默认：true会自动隐藏。
Keyboard / Mousewheel(键盘、鼠标控制选项)
keyboardControl	boolean	false	是否开启键盘控制Swiper切换。设置为true时，能使用键盘方向键控制slide滑动。
mousewheelControl	boolean	false	是否开启鼠标控制Swiper切换。设置为true时，能使用鼠标滑轮控制slide滑动。
mousewheelForceToAxis	boolean	false	当值为true让鼠标滑轮固定于轴向。当水平mode时的鼠标滑轮只有水平滚动才会起效，当垂直mode时的鼠标滑轮只有垂直滚动才会起效。普通家用鼠标只有垂直方向的滚动。
Hash Navigation(散列导航)
hashnav	boolean	false	如需使用散列导航（有点像锚链接）将此参数设置为true。
Images(图片选项)
preloadImages	boolean	true	默认为true，Swiper会强制加载所有图片。
updateOnImagesReady	boolean	true	当所有的内嵌图像（img标签）加载完成后Swiper会重新初始化。
lazyLoading	boolean	false	设为true开启图片延迟加载，使preloadImages无效。
lazyLoadingInPrevNext	boolean	true	设置为true允许将延迟加载应用到最接近的slide的图片（前一个和后一个slide）。
lazyLoadingOnTransitionStart	boolean	true	默认当过渡到slide后开始加载图片，如果你想在过渡一开始就加载，设置为true
Loop(环路)
loop	boolean	false	设置为true 则开启loop模式。loop模式：会在wrapper前后生成若干个slides让slides看起来是衔接的，用于无限循环切换。
loopAdditionalSlides	number	0	loop模式下会在slides前后复制若干个slide,，前后复制的个数不会大于原总个数。
loopedSlides	number	null	在loop模式下使用slidesPerview:’auto’,还需使用该参数设置所要用到的loop个数。
Controller(双向控制)
control	[Swiper Instance]	undefined	设置为另外一个Swiper实例开始控制该Swiper。
controlInverse	boolean	false	设置为true时控制方向倒转。
Callbacks(回调函数)
runCallbacksOnInit	boolean	true	初始化时触发 [Transition/SlideChange] [Start/End] 回调函数。这些回调函数会在下次初始化时被清除如果initialSlide不为0。
onInit(swiper)	function		回调函数，初始化后执行。
onSlideChangeStart(swiper)	function		回调函数，滑块释放时如果触发slider切换则执行。free模式下无效。
onSlideChangeEnd(swiper)	function		回调函数，slider切换结束时执行。free模式下无效。
onTransitionStart(swiper)	function		回调函数，过渡开始时触发，接收Swiper实例作为参数。
onTransitionEnd(swiper)	function		回调函数，过渡结束时触发，接收Swiper实例作为参数
onTouchStart(swiper, event)	function		回调函数，当碰触到slider时执行。可选Swiper和touchstart事件作为参数。
onTouchMove(swiper, event)	function		回调函数，手指触碰Swiper并滑动（手指）时执行。此时slide不一定会发生移动
onTouchMoveOpposite(swiper, event)	function		回调函数，当手指触碰Swiper并且没有按照direction设定的方向移动时执行。可选Swiper实例和touchmove事件作为参数。
onSliderMove(swiper, event)	function		回调函数，手指触碰Swiper并拖动slide时执行。
onTouchEnd(swiper, event)	function		回调函数，当释放slider时执行。
onClick(swiper, event)	function		回调函数，当你点击或轻触Swiper 300ms后执行。
onTap(swiper, event)	function		回调函数，当你轻触(tap)Swiper后执行。在移动端，click会有 200~300 ms延迟，所以请用tap代替click作为点击事件。
onDoubleTap(swiper, event)	function		回调函数，当你两次轻触Swiper 时执行，类似于双击。
onImagesReady(swiper)	function		回调函数，所有内置图像加载完成后执行，同时“updateOmImagesReady”需设置为“true’。
onProgress(swiper, progress)	function		回调函数，当Swiper的progress被改变时执行。
onReachBeginning(swiper)	function		回调函数，Swiper切换到初始化位置时执行。
onReachEnd(swiper)	function		回调函数，当Swiper切换到最后一个Slide时执行。
onDestroy(swiper)	function		回调函数，销毁Swiper时执行。
onSetTranslate(swiper, translate)	function		回调函数，每次当Swiper开始过渡动画时持续执行。transtion获取到的是Swiper的speed值。
onSetTransition(swiper, transition)	function		回调函数，wrapper改变其位置时执行。返回当前transform 的偏移量的对象。
onAutoplayStart(swiper)	function		回调函数，自动切换开始时执行。
onAutoplayStop(swiper)	function		回调函数，自动切换结束时执行。
onLazyImageLoad(swiper,slide, image)	function		回调函数，图片延迟加载开始时执行。
onLazyImageReady(swiper, slide, image)	function		回调函数，图片延迟加载结束时执行。
Namespace(命名空间)
slideClass	string	‘swiper-slide’	设置slide的类名。
slideActiveClass	string	‘swiper-slide-active’	设置活动块的类名。
slideVisibleClass	string	‘swiper-slide-visible’	设置可视块的类名。
slideDuplicateClass	string	‘swiper-slide-duplicate’	loop模式下被复制的slide的类名。
slideNextClass	string	‘swiper-slide-next’	active slide的下一个slide的类名。
slidePrevClass	string	‘swiper-slide-prev’	active slide的前一个slide的类名。
wrapperClass	string	‘swiper-wrapper’	设置wrapper的css类名。
bulletClass	string	‘swiper-pagination-bullet’	pagination分页器内元素的类名。
bulletActiveClass	string	‘swiper-pagination-bullet-active’	pagination分页器内活动(active)元素的类名。
paginationHiddenClass	string	‘swiper-pagination-hidden’	分页器隐藏时的类名。
buttonDisabledClass	string	‘swiper-button-disabled’	前进后退按钮不可用时的类名。

Swiper常用方法

1、mySwiper.destroy()

销毁Swiper(true)。销毁所有绑定的监听事件，移除鼠标键盘事件，释放浏览器内存。

2、mySwiper.startAutoplay()

开始自动切换。一般用来做“Play”按钮。

3、mySwiper.stopAutoplay()

停止自动切换。一般用来制作“pause”按钮。

4、mySwiper.slideNext(runCallbacks, speed)

滑动到下一个滑块。

5、mySwiper.slidePrev(runCallbacks, speed)

滑动到前一个滑块。

6、mySwiper.slideTo(index, speed, runCallbacks)

滑动到到指定滑块。
index:必选，num，指定将要切换到的slide的索引，第一个为0
speed:可选，num(单位ms)，切换速度
runCallbacks:可选，boolean，设置为false时不会触发onSlideChange回调函数。

附：

Swiper官网：http://www.idangero.us/sliders/swiper/index.php

Swiper中文网：http://www.swiper.com.cn/

转自：http://qqfe.org/

Web前端分享

_______________人如代码，规矩灵活；代码如诗，字句精伦。

移动端触摸滑动插件Swiper

公告