首页 > 代码库 > Swiper 中文API手册（share）
Swiper 中文API手册（share）
本文分享自 http://miliwo.com/w/1859/26062
---------------------------华丽的分割线----------------------------------
最近使用Swipe.js，发现中文的资料很少，试着翻译了一下。能力有限，翻译难免错漏，欢迎指出，多谢！
翻译自：http://www.idangero.us/sliders/swiper/api.php
http://www.idangero.us/sliders/swiper/index.php
一了解Swiper
Swiper 是一款免费以及轻量级的移动设备触控滑块的框架，使用硬件加速过渡（如果该设备支持的话）。主要使用与移动端的网站、网页应用程序（web apps），以及原生的应用程序（native apps）。主要是为IOS而设计的，同时，在Android、WP8系统以及现代桌面浏览器也有着良好的用户体验。
特征（feature)
1、1：1触控运动
Swiper默认提供1:1的触控距离，当然，这个比率是可以设置的。（touchRatio）
2、触控模仿
这个功能对于开发桌面网站会很有用。简单来说，就是因为Swiper能够让鼠标事件表现得像触屏事件（点击以及拖曳滑块）
3、水平/垂直
Swiper运动主要有两种模式，horizontal(水平滑动)以及vertical（垂直运动的滑动）
4、自由模式（Free Mode）
这种模式下能够让slides 无需定位，就像通常的滑动条。（看下面的例子）
5、旋转调整 （rotation/resize）
Swiper 在移动设备旋转后能自适应尺寸。
6、响应式
能使用百分比的宽高定义slides,为移动端提供不同的解决方案。
7、滑动阻止
简单来说，就是，只能使用一种模式，水平或者垂直滑动。
8、抵抗反弹（resistant bounds）
Swiper能够提供一种机制，就是当滑动滑块超过最左以及最右（最上或最下）的位置时触发的一种抵御机制。
9、原生要素（native momentum）
有不少的原生东西提供给Swiper。
10、内建分页控制
Swiper能够快速生成内建的分页控制（pagination）,指定html 某一标签为pagination，Swiper就能做很多东西了。
11、自动播放
只用设置延迟时间，Swiper就会自动地轮播slides直到你触碰该滑块（touch）为止。
12、循环模式（Loop mode）
该种模式下，你能够无限滑动滑块，到最后一个之后会跳转回第一个。
13、旋转模式（Carousel mode）
Swiper 能够让你在slides父容器下设置你所需要展示的slides数量。
14、滑动容器
在该特征下能够使用Swiper在一些简单的能滑动的区域里，没有slides。在Apps里十分有用。
15、嵌套Swipers
能够将Swipers嵌套入各种不同的Swiper 的slide里，例如垂直的或水平的。
16、任意的HTML 标签
可以将任一的HTML 内容放到slide里，不止仅限于图像。
17、硬件加速
swiper 使用硬件加速技术（如果该移动设备支持的话）能够得到良好流畅的动画效果以及优美的外观，尤其是在IOS设备里。
18、丰富的API
Swiper拥有丰富的API接口。（不过关于中文文档似乎不多，没找着。）能够让开发者生成个人独有的分页器（pagination），上下滑块的按钮以及4个回调函数：onTouchStart,onTouchMove,onTouchEnd,onSlideSwitch。
19、灵活的配置
Swiper在初始化的时候能够接受多个参数以便让其尽可能的灵活。能够配置动画的速度（speed），模式（mode水平抑或垂直的），以及自由模式（free mode）...以及其他..
20、插件API（Plugins API）
Swiper从1.7版本开始就变得强大起来了，因为有更多而简单的插件API允许开发者创造属于自己的Swiper 插件或通过Swiper的核心创制hooks(挂钩)（该官网处提供了几款优秀的插件Swiper smooth progress, Swiper hash navigation,swiper scrollbar）
21、良好的兼容性
Swiper通用性的测试环境：移动端的Safari（iOS5下），Android 2.1+，windows Phone 8,以及最新版本的谷歌浏览器（Chrome），Safari，Firefox，IE10 以及欧朋浏览器（Opera）
22、老版本IE的兼容
Swiper 2.x 开始，通过DOM动画，而非css transitions 兼容IE7 以上（需要包含jQuery），因为IE7不支持css3 transitions....简单来说，支持IE7 以上版本。
23、独立性
Swiper不依赖像jQuery那样的js类库，因此能够让Swiper更加的小型以及快速。所以Swiper能够很安全地应用诸如jQuery、jQuery Mobile，jQTouch等等其他的js类库。
24、超轻量级
压缩后仅仅10KB左右。
以上，就是Swiper能够做的，应用以上特征就使用原生属性方法能够快速生成令人惊叹的触控接口以及apps。
Usage: 1、下载swiper最新版本https://github.com/nolimits4web/Swiper 2、在HTML Head中添加Swiper‘s CSS and JS: 1 <head>2 ....3 <link rel="stylesheet" href="path_to_css/idangerous.swiper.css">4 <script defer src="path_to_js/idangerous.swiper-2.x.min.js"> </script>5 ....6 </head>其中引用的文件名以下载的为准。 3、使用下面的HTML布局 1 <div class="swiper-container"> 2 <div class="swiper-wrapper"> 3 <!--First Slide--> 4 <div class="swiper-slide"> 5 <!-- 这里添加第一个HTML内容 --> 6 </div> 7 <!--Second Slide--> 8 <div class="swiper-slide"> 9 <!-- 这里添加第二个HTML内容 -->10 </div> 11 <!--Third Slide-->12 <div class="swiper-slide"> 13 <!-- 这里添加第三个HTML内容 -->14 </div>15 <!--Etc..-->16 </div>17 </div>4、打开下载的文件中的idangerous.swiper.css，设置Swiper‘s的宽度以及高度（在文件的末尾） /* 指定swiper 容器尺寸: */ .swiper-container, .swiper-slide { width: 500px; height: 200px;}5、初始化Swiper 在文档开始处，（或在窗口加载时） 1 <script type="text/javascript"> 2 /*====== 3 使用文档添加事件或窗口加载事件 4 例如: 5 window.onload = function() { ...代码 ...} 6 或者document.addEventListener(‘DOMContentLoaded‘, function(){ ...代码... }, false) 7 =======*/ 8 window.onload = function() { 9 var mySwiper = new Swiper(‘.swiper-container‘,{10 //添加需要的选项:11 mode:‘horizontal‘,12 loop: true 13 //等等..14 }); 15 }16 })17 </script>API: new Swiper（container,options） container: 字符串要求，Swiper‘s容器的css选择器。在上面的HTML代码中就必须等于“.swiper-container”; options:-对象，可选择的。Swiper参数，详情见下： 用法： 1 var mySwiper = new Swiper(".swiper-container",{2 speed:750,3 mode:"vertical"4 })返回拥有众多有用函数（functions）以及方法(methods)的对象: ·mySwiper.disableMousewheelControl()-滑动中禁掉鼠标滑轮（mousewheel control）控制 ·mySwiper.enableMousewheelControl()-能够使用禁掉了的鼠标滑轮 ·mySwiper.enableKeyboardControl()-滑动中键盘控制可用 ·mySwiper.disableKeyboardControl()-禁用滑动中键盘控制 ·mySwiper.swipeNext()-执行过渡动画到下一滑块（slide）(简单来说就是滑动到下一个页面) ·mySwiper.swipePrev()-执行过渡动画到上一滑块 ·mySwiper.swipeTo(index,speed,runCallbacks) - 执行过渡到索引下标数字等于传入参数“index”的页面（slide）处，速度为传入的参数“speed”。同时可将“runCallbacks”设置为false（默认为“true”），那么transition（过渡）不会产生onSlideChange回调函数。 ·mySwiper.browser.ie10 - 返回 “true”如果浏览器为IE10 ·mySwiper.browser.is8 -返回 “true”如果浏览器为IE8 ·mySwiper.support.touch -返回 “true”如果浏览器支持触屏 ·mySwiper.support.transforms -返回 “true”如果浏览器支持css3 transforms(变形) ·mySwiper.support.transforms3d -返回 “true”如果浏览器支持css3 3D transforms(变形) ·mySwiper.support.transitions -返回 “true”如果浏览器支持css3 transitions(过渡) ·mySwiper.activeSlide() - 返回当前活动块（slide）（slide 实例，HTML元素） ·mySwiper.clickedSlideIndex - 返回触控/点击块（slide）的索引（数字）。只适用于“onSlideTouch”和“onSlideClick” 回调函数中。 ·mySwiper.clickedSlide - 返回触控/点击块（slide）（slide实例，HTML元素）。只适于“onSlideTouch”和“onSlideClick” 回调函数中。 ·mySwiper.activeIndex- 返回当前活动块的索引（number） ·mySwiper.activeLoopIndex- 返回当前活动块在loop 模式下的索引（number） ·mySwiper.activeLoaderIndex- 返回当前活动块在loader模式下的索引（number） ·mySwiper.previousIndex- 返回上一个活动块的索引（number） ·mySwiper.startAutoplay()-开始自动播放。应用于自定义“Play”和“Pause”按钮 ·mySwiper.stopAutoplay()-停止自动播放。应用于自定义“Play”和“Pause”按钮 ·mySwiper.destroy(removeResizeEvent) -移除所有绑定的事件监听（窗口的尺寸改变事件【如果removeResizeEvent的值不等于“false”】，容器（wrapper）的触控事件，以及文档的鼠标事件），对于添加/移除滑块，页面到文档时非常有用，能够释放浏览器内存。 ·mySwiper.resizeFix()-调用这个方法当你改变swiper‘s 的尺寸而没有改变窗口大小时。 ·mySwiper.reInit()- 重新初始化Swiper。对于动态添加/移除滑块非常有用。 ·mySwiper.width 返回Swiper容器的宽度 ·mySwiper.height返回Swiper容器的高度 ·mySwiper.isTouched 返回布尔值，当触控该slide时返回“true” ·mySwiper.positions - 返回包含x,y坐标的wrapper对象 ·mySwiper.touches - 返回包含触控信息的对象数组 ·mySwiper.params - 获取对象初始化参数，能够在初始化之后改变/重写该参数，如： mySwiper.params.speed = 500; ·mySwiper.getWrapperTranslate(axis)-返回当前容器“位移（translate）"【css3 transform ->translate】,即x,或y轴的偏移量。”axis“-参数为字符串”x“或”y“,对应于水平模式及垂直模式。 ·mySwiper.setWrapperTranslate(x,y,z) - 手工设置css3 transform‘s translate 的值。x,y and z -为数字 ·mySwiper.wrapperTransitionEnd(callback,permanent) - 使用该方法当Swiper ”transitionEnd“事件触发后能够自定义回调函数（在swipeNext,swipePrev,swipeTo 以及swipeReset 函数之后）: callback-函数（function）。默认状态下（如果permanent 值为false）transitions只执行一次 permanent - boolean . 默认状态下为false，当设置为真时该回调函数callback会执行多次。
选项（options） Swiper 初始化 支持下列中的参数
自由模式与滑块容器（Free Mode and Scroll Container)
块（slides）偏移
触屏/鼠标事件效应（Touch/mouse interactions ）
Navigation
Pagination（分页器）(指示器)
命名空间namespace
回调函数（Callbacks）
Example 以下需要引用jQuery文件 1 <script src="http://www.mamicode.com/js/jquery-1.10.1.min.js"></script> 2 3 <script type="text/javascript"> 4 5 $(document).ready(function(){ 6 7 var mySwiper = $(‘.swiper-container‘).swiper({ 8 9 mode : ‘vertical‘, //选择垂直模式，10 11 speed : 500, //设置动画持续时间500ms12 13 freeMode : true, //开启自由模式14 15 freeModeFluid : true, //开启‘fluid‘自由模式16 17 onTouchStart : function() {18 19 //触控滑块时执行代码20 21 alert(‘OMG you touch the slide!‘) 22 23 }24 25 }26 27 })28 29 </script>
Callbacks API 从Swiper2.4版本开始增加了一些回调函数，现在添加一些函数到上面。 当初始化Swiper时，旧版本指定回调函数的方式： 1 $(document).ready(function(){ 2 3 var mySwiper = new Swiper(‘.swiper-container‘,{ 4 5 mode:‘vertical‘, 6 7 speed: 600, 8 9 onSlideChangeStart: function(swiper){10 11 alert(‘Hello 1‘);12 13 }14 15 }); 16 17 });新版本中能够实现无需完全重写onSlideChangeStart参数，可以添加新函数到回调函数中。 1 mySwiper.addCallback(‘SlideChangeStart‘, function(swiper){2 3 alert(‘Hello 2‘);4 5 }) 你会发觉在过渡动画开始时弹出“Hello 1” 以及“Hello 2“，该种方式下addCallback方法需要注意该回调函数名不包含”on“。 解除（fire）callback 函数语句： mySwiper.fireCallback(‘SlideChangEnd‘,mySwiper); 移除（remove）callbacks: mySwiper.removeCallback(‘SlideChangEnd‘); Slides API Swiper提供强大的Slides API，能够动态生成/删除/操作Slides（滑块） Slide 实例 这个实例是简单的HTML元素但扩展了非常有用的方法。 下面的例子变量mySwiper包含了属性和方法的Swiper对象。 1 <script type="text/javascript"> 2 $(document).ready(function(){ 3 var mySwiper = $(‘.swiper-container‘).swiper({ 4 mode : ‘vertical‘, //切换到垂直模式 5 speed : 500, //动画持续时间 6 freeMode : true, //启动自由模式 7 freeModeFluid : true, //启动‘fluid‘自由模式 8 onTouchStart : function() { 9 //触碰滑块是的事件10 alert(‘OMG you touch the slide!‘) 11 }12 }13 })</script>通过调用一下方法，你能生成Swiper滑块实例： mySwiper.createSlide(html,slideClassList,element),其中：
1 var mySwiper = $(".swiper-container").swiper({...some optins...}) 2 3 //创建一个新的swiper实例 4 5 var newSlide = mySwiper.createSlide("<p>Here is my new slide</p>"); 6 7 //生成的HTML滑块："<div class="swiper-slide"><p>Here is my new slide</p></div>" 8 9 var newSlide = mySwiper.createSlide("<p>Hello</p>","swiper-slide red-slide","span");10 11 //生成的HTML滑块："<span class="swiper-slide red-slide"><p>Hello</p></span>""newSlide"变量包含在新建Slide实例之后,但如今还在内存中，并不在slider中。为了将其添加到slider中，能够使用一下链式方法有效地添加到Slide实例中：
1 //例子 2 3 var mySwiper = $(".swiper-container").swiper({...some optins...}) 4 5 var newSlide = mySwiper.createSlide("<p>Here is my new slide</p>"); 6 7 newSlide.append()//newSlide添加到所有已存在的slides后面 8 9 var newSlide = mySwiper.createSlide("<p>Hello</p>","swiper-slide red-slide","span");10 11 newSlide.prepend()//-newSlide添加到所有已存在的slides的前面（第一个位置）12 13 //复制、插入Slide14 15 var clonedSlide = newSlide.clone();16 17 clonedSlide.append();18 19 //crazy 链式20 21 var newSlide = mySwiper.createSlide("<p>Here is my new slide</p>");22 23 newSlide.prepend().clone().append().clone().inertAfter(2)24 25 //-新创建的slide被添加到所有已存在的slide前面，然后复制slide并添加到最后，接着在复制添加到index为2的位置上
还有一些有用的方法：
如果innerHTML没有指定，返回slide中inner html内容。
1 //例子 2 3 var mySwiper = $(‘.swiper-container‘).swiper({...some options...}) 4 5 //创建slide实例 6 var newSlide = mySwiper.createSlide(‘<p>Here is my new slide</p>‘); 7 newSlide.append().clone().html(‘<p>New HTML</p>‘).prepend() 8 // 新创建的slide被添加到最后，然后复制该slide并添加html内容，最后插入到第一个位置 9 10 var newSlide = mySwiper.createSlide(‘<p>Here is my new slide</p>‘);11 alert(newSlide.html()) // -> <p>Here is my new slide</p>12 13 Store/Get data:14 newSlide.prepend().setData(‘apples‘,[‘iMac‘, ‘MacBook Pro‘, ‘iPhone‘, ‘iPad‘])15 newSlide.getData(‘apples‘) // -> [‘iMac‘, ‘MacBook Pro‘, ‘iPhone‘, ‘iPad‘]16 17 newSlide.data(‘apple‘,‘iPad‘);18 newSlide.data(‘apple‘) //->‘iPad‘
Swiper Slides 好的，让我们 看看swiper是如何操作存在的slides（添加/移除）
html(string[字符型],required[必需的])-生成的滑块的HTML元素的内容 slideClassList(stirng[字符型],optional[可选的])- 创建类”class“属性。缺省值为"swiper-slide " element(string[字符型],optional[可选的])-创建滑块的HTML标签，缺省值为"div"
1 //例子: 2 3 //创建slide并插入 4 mySwiper.appendSlide(‘Hello World‘) 5 //或者: 6 var newSlide = mySwiper.createSlide(‘Hello World‘) 7 mySwiper.appendSlide(newSlide) 8 //或者: 9 mySwiper.appendSlide( mySwiper.createSlide(‘Hello World‘) )10 11 //复制第一个slide并插入到最后12 mySwiper.getFirstSlide().clone().append();13 //或者:14 mySwiper.appendSlide( mySwiper.getSlide(0).clone() )15 16 //复制第二个slide修改内容并插入到最后17 mySwiper.getSlide(1).clone().html(‘Hello New World!‘).append();18 19 //移除最后一个slide20 mySwiper.removeLastSlide()21 22 //移除第二个slide23 mySwiper.removeSlide(1)24 25 //Trick: 更换第一与第二个slide位置26 mySwiper.getSlide(0).insertAfter(1)27 28 //Trick: 移动第一个slide到最后一个位置29 mySwiper.getFirstSlide().append()30 31 //slide数量32 alert(mySwiper.slides.length)33 34 //改变每个slide的html35 for (var i = 0; i < mySwiper.slides.length; i++) {36 var slide = mySwiper.slides[i]37 slide.html(‘<p> My index number is ‘+i+‘ </p>‘)38 }重要备注 当使用改变slides数量的方法时（例如append,prepend,remove等等），reInit()方法会被调用然后slides数量会自动重新计算。所以非常不推荐动态添加/删除slides时在"for"循环中使用"slides.length" ，因为这样做可能产生死循环。 |
Swiper 中文API手册（share）