首页 > 代码库 > Swiper 中文API手册（share）
Swiper 中文API手册（share）
翻译自：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="http://www.mamicode.com/path_to_css/idangerous.swiper.css">4 <script defer src="http://www.mamicode.com/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> |
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会执行多次。
Swiper 中文API手册（share）