移动端触摸滑动插件Swiper
04/02/2015
一、了解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>
…
<link rel=”stylesheet” href=”path/to/swiper.min.css”></head><body>
…
<script src=”path/to/swiper.min.js”></script></body></html>
如果你的页面加载了jQuery.js或者zepto.js，你可以选择使用更轻便的swiper.jquery.min.js。
<!DOCTYPE html><html><head>
…
<link rel=”stylesheet” href=”path/to/swiper.min.css”></head><body>
…
<script src=”path/to/jquery.js”></script>
<script src=”path/to/swiper.jquery.min.js”></script></body></html>
2.HTML内容。
<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 class=”swiper-button-prev”></div>
<div class=”swiper-button-next”></div>
<!– 如果需要滚动条 –>
<div class=”swiper-scrollbar”></div></div>
3.你可能想要给Swiper定义一个大小。
.swiper-container {
width: 600px;
height: 300px;}
4.初始化Swiper：最好是挨着</body>标签
<script>
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内容的后面，则需要在页面加载完成后再初始化。
<script type=”text/javascript”>
window.onload = function() {
…
}
</script>
或者这样（Jquery和Zepto）
<script type=”text/javascript”>
$(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/