Swiper Usage&&API

时间：2023-02-04 10:16:29

最近使用Swipe.js，发现中文的资料很少，试着翻译了一下。能力有限，翻译难免错漏，请指出，多谢！如果想获得国外较多而全的文档，还是用google。

一了解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:

<head>

....

<link rel="stylesheet" href="path_to_css/idangerous.swiper.css">

<script defer src="path_to_js/idangerous.swiper-2.x.min.js"></script>

....

</head>

其中引用的文件名以下载的为准。

3、使用下面的HTML布局

div class="swiper-container">

<div class="swiper-wrapper">

<!--First Slide-->

<div class="swiper-slide">

<!-- 这里添加第一个HTML内容 -->

</div>

<!--Second Slide-->

<div class="swiper-slide">

<!--  这里添加第二个HTML内容 -->

</div>

<!--Third Slide-->

<div class="swiper-slide">

<!--  这里添加第三个HTML内容 -->

</div>

<!--Etc..-->

</div>

</div>

4、打开下载的文件中的idangerous.swiper.css，设置Swiper's的宽度以及高度（在文件的末尾）

/* 指定swiper 容器尺寸: */

.swiper-container, .swiper-slide {

width: 500px;

height: 200px;

}

5、初始化Swiper 在文档开始处，（或在窗口加载时）

<script type="text/javascript">

/*======

使用文档添加事件或窗口加载事件

例如:

window.onload = function() { ...代码 ...}

或者document.addEventListener('DOMContentLoaded', function(){ ...代码... }, false)

=======*/

window.onload = function() {

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

//添加需要的选项:

mode:'horizontal',

loop: true

//等等..

});

}

})

</script>

API:

new Swiper（container,options）

container: 字符串要求，Swiper's容器的css选择器。在上面的HTML代码中就必须等于“.swiper-container”;

options:-对象，可选择的。Swiper参数，详情见下：

用法：

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

speed:750,

mode:"vertical"

})

返回拥有众多有用函数（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 初始化 支持下列中的参数

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明）

speed

300

600

slides滑块动画之间的持续时间（单位ms）

eventTarget

'wrapper'

'container'

swipers事件对象，默认状态下所有的触控事件只能用于wrapper。如若需要其他元素包含在container内以及使用swipers,那么可以使用'container'. 2.4.2版本新增

autoplay

5000

-

过渡延迟时间（单位ms），参数没有指定的情况下，不生效，（补充：当用户操作后autoplay失效）

autoplayDisableOninteraction

true

false

当设置为false时，用户操作之后（swipes,arrow以及pagination 点击）autoplay不会被禁掉，用户操作之后每次都会重新启动autoplay。

autoplayStopOnLast

false

true

设置为false后autoplay在最后一个块下失效（在没有设置loop的情况下）

mode

'horizontal'

'vertical'

slides滑动方式，水平或垂直

loop

false

true

true 为loop模式生效

loopAdditionalSlides

0

2

loop模式下slides数量增加个数

loopedSlides

1

2

在loop模式下使用slidesPerview:'auto',还需使用该参数设置所要用到的loop个数

slidesPerView

1

4

旋转模式下，设置slider's容器能够同时显示的slides数量。另外，支持'auto'值，会根据容器container的宽度调整slides数目。‘auto’不兼容loop模式

slidesPerViewFit

true

false

仅当已设置了slidesPerView:'auto'，以及当slides的宽度大于容器，该参数生效。默认为true然后宽度大的slide 过渡时会划分为边缘的两部分。为false时，slide transition 会划分为比容器container大的多个slides

slidesPerGroup

1

2

定义slides的数量多少为一组，在旋转模式下有效。（carousel mode）

calculateHeight

false

true

当值为true时，Swiper根据slides内容计算容器高度。响应式布局中或不知道slides高度时十分有用（就像响应式的图片）

roundLengths

false

true

值为true时，Swiper会四舍五入宽度和高度，在响应式的滑块中包含误差时十分有用。

cssWidthAndHeight

false

true

值为true以及Swiper中的container，wrapper和slides没有高度

updateFormElements

true

false

当所有的内嵌图像（img标签）加载完成后Swiper会重新初始化。

watchActiveIndex

false

true

如果启用触屏事件期间会重新动态计算活动块的索引。

visiblilityFullfit

false

true

如果启用，仅有“可视”的slides会最后适应容器的大小

autoResize

true

false

值为false时，窗口尺寸改变时，禁掉slides自适应

DOManimation

true

false

在不支持css transitions(IE7-9)的浏览器上是否使用自定义的DOM动画

resistance

true

false

值为false时禁用resistant bounds（抵抗反弹）,设置为‘100%'时启用resistant（抵抗）模式

noSwiping

false

true

值为true时，当swiper新增类”noSwipingClass“的滑动块时，禁掉该元素的滑动。

preventLinks

true

false

启用时当碰触滑块（slides）时禁止<a>标签链接

preventLinksPropagation

false

true

如滑动过程中需要跟preventLinks一起禁用stopPropagation，设置值为true

initialSlide

2

0

初始块（页面）的索引

useCSS3Transforms

true

false

值为false时禁用css3 transforms（减少内存，提高性能，同时也降低了美观）,同时使用wrapper的left/top属性代替。

*模式与滑块容器（Free Mode and Scroll Container)

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明

freeMode

false

true

若为真slide坐标不固定

freeModeFluid

false

true

若为真，释放滑块之后仍会滑动一小会

scrollContainer

false

true

设置为真时，让Swiper看上去像滑动区（scrollable area）

momentumRatio

1

2

设置的值越大，当释放滑块时的动量距离越大

momentumBounce

true

false

false时禁用*模式下的（free mode）动量弹性

momentumBounceRatio

1

2

值越大产生的动量弹性（momentum bounce）效果越明显

块（slides）偏移

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明

centeredSlides

false

true

若为真，那么活动块会居中，而非默认状态下的居左

offsetPxBefore

0

100

指定slides与wrapper左边框的偏移量

offsetPxAfter

0

100

指定slides与wrapper右边框的偏移量

offsetSlidesBefore

0

2

滑块slides与wrapper左边框的偏移量等于等于指定滑块slides个数的宽度。这在响应式布局中而你又不知道slides宽度时，将十分有用。

offsetSlidesAfter

0

2

滑块slides与wrapper右边框的偏移量等于等于指定滑块slides个数的宽度。这在响应式布局中而你又不知道slides宽度时，将十分有用。

触屏/鼠标事件效应（Touch/mouse interactions ）

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明

touchRatio

1

0.8

触屏比率

simulateTouch

true

false

true,Swiper接受鼠标事件时与触屏事件相似。（单击以及拖曳滑块）

onlyExternal

false

true

值为true时，只能使用扩展API函数内的swipeRight 或swiperLeft改变slides滑动，其他失效。正如例子里的tabs切换十分有用

followFinger

true

false

值为false时，仅当你释放slide时才会滑动，当你用手指按住滑块它不会动。

grabCursor

false

true

该选项给Swiper用户提供小小的贴心应用，值为true时，光标在Swiper上时成手掌状。

shortSwipes

true

false

值为false时，禁用short swipes

longSwipesRatid

0.5

0.3

Swiper 中到上/下滑块的触发率

moveStartThreshold

false

100

滑动的临界值，临界值单位为px，如果触屏距离小于该值滑块不会运动。

Navigation

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明

keyboardControl

false

true

值为true时，水平模式下，能使用键盘左右方向键滑动，垂直模式下能使用上下方向键滑动

mousewheelcontrol

false

true

值为true时，能够使用鼠标滑轮滑动swiper

mousewheelControlForceToAxis

false

true

值为真时，鼠标轮滑会改变轴向，所以水平模式下的鼠标滑轮只作用于水平鼠标滑块，垂直的作用于垂直模式。

Pagination（分页器）(指示器)

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明

pagination

-

'.my-pagination'

css选择器中的分页。或者HTML元素内的分页元素

paginaClickable

false

true

值为真时，当单击指示器时会执行过渡动画到目标slide

paginationAsRange

true

为真时，跟可见块相关的指示器按钮会新增css类。当使用slidesPerview超过1时会十分有用。

createPagination

true

false

值为真时，Swiper会在slider内生成与slides数量相同的SPAN标签。所有这些生成的span标签都在pagination容器内。每一个span标签都有一个”swiper-pagination-switch“类名，活动的span（及当前slide下的）有一个为”swiper-active-switch’的类名，对于这些使用样式十分有用。

命名空间namespace

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明

wrapperClass

'swiper-wrapper'

'my-wrapper'

Swiper内wrapper的css类。具体查看上面的例子

slideClass

'swiper-slide'

'my-slide'

Swiper内slide的css类名。具体查看上面的例子

slideActiveClass

'swiper-slide-active'

'my-active-slide'

Swiper内活动块的css类名。。。

slideActiveClass

'swiper-slide-visible'

'my-visible-slide'

Swiper内可视块的css类名。。。

slideElement

'div'

'li'

使用单一滑块的标签

noSwipingClass

'swiper-no-swiping'

'stop-swiping'

html元素使用的类名，当noSwiping参数设置为true时，用于禁止滑动

paginationElement

'span

'div'

使用唯一指示按钮的标签

paginatinElementClass

'swiper-pagination-switch'

'my-switch'

使用多个指示按钮的类名

paginationActiveClass

'swiper-active-switch'

'my-active-switch'

当前活动指示按钮的类名

paginationVisibleClass

'swiper-visible-switch'

'my-visible-switch'

可见指示按钮的类名

回调函数（Callbacks）

Parameter（参数）

Default Value（默认值

Example（例子）

Description（说明

queueStatCallbacks

false

true

设置为true时，‘slideChangeStart’回调函数入队，所以在快速滑动过程中回调函数只被调用一次。

queueEndCallbacks

false

true

设置为true时，‘slideChangeEnd’回调函数入队，所以在快速滑动结束后回调函数只被调用一次。

onFirstInit

-

function(swiper)
{
//执行代码
}

回调函数，首次初始化后马上执行

onInit

-

function(swiper){
//执行代码

}

回调函数，在其他所有的初始化/再初始化后马上执行

onSwiperCreated

-

function(swiper){
//执行代码

}

回调函数，当Swiper初始化完成，loop，pagination，等其他参数或方法生成之后执行

onTouchStart

-

function(swiper){
//执行代码

}

回调函数，当碰触到slider时马上执行

onTouchMove

-

function(swiper){
//执行代码

}

回调函数，当碰触slider到释放期间执行。

onTouchEnd

-

function(swiper){
//执行代码

}

回调函数，当释放slider时执行

onSlideReset

-

function(swiper){
//执行代码

}

回调函数，释放滑块之后，滑块将要滑到当前活动的slide时执行。freeMode模式下不生效。

onSlideChangeStart

-

function(swiper){
//执行代码

}

回调函数，当动画开始过渡到另一slide时执行，即动画开始时执行。freeMode模式下不生效。

onSlideChangeEnd

-

function(swiper){
//执行代码

}

回调函数，过渡动画结束后执行，即滑块活动停止后执行。freeMode模式下不生效。

onSlideNext

-

function(swiper){
//执行代码

}

回调函数，与onSlideChangeStart相似，但该函数只能在滑向下一slide开始时生效

onSlidePrev

-

function(swiper){
//执行代码

}

回调函数，与onSlideChangeStart相似，但该函数只能在滑向上一slide开始时生效

onSlideTouch

-

function(swiper){
//执行代码

}

回调函数，当触碰事件发生后生效。与onToucStart相似，不过该函数会返回.clickedSlide和.clickedSlideIndex的值

onImageReady

-

function(swiper){
//执行代码

}

回调函数，所有内置图像加载完成后执行，同时“updateOmImagesReady”需设置为“true’

onMomentumBounce

-

function(swiper){
//执行代码

}

回调函数，执行于动量反弹（momentum bounce）过程中

onResistanceBefore

-

function(swiper,p){
//执行代码

}

回调函数，执行于negative resistance过程中。p-返回抵抗距离。

onResistanceAfter

-

function(swiper,p){
//执行代码

}

回调函数，执行于positive resistance过程中。p-返回抵抗距离。

onSetWrapperTransition

-

function(swiper,duration){

//执行代码

}

回调函数，每次当Swiper开始动画时执行

onSEtWrapperTransform

-

function(swiper,transform){

//执行代码

}

回调函数，swiper的容器wrapper改变其坐标时执行。返回带当前transform 的偏移量的对象。

Example

以下需要引用jQuery文件

<script src="js/jquery-1.10.1.min.js"></script>

<script type="text/javascript">

$(document).ready(function(){

var mySwiper = $('.swiper-container').swiper({

mode : 'vertical', //选择垂直模式，

speed : 500, //设置动画持续时间500ms

freeMode : true, //开启*模式

freeModeFluid : true, //开启'fluid'*模式

onTouchStart : function() {

//触控滑块时执行代码

alert('OMG you touch the slide!')

}

}

})

</script>

Callbacks API

从Swiper2.4版本开始增加了一些回调函数，现在添加一些函数到上面。

当初始化Swiper时，旧版本指定回调函数的方式：

$(document).ready(function(){

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

mode:'vertical',

speed: 600,

onSlideChangeStart: function(swiper){

alert('Hello 1');

}

});

});

新版本中能够实现无需完全重写onSlideChangeStart参数，可以添加新函数到回调函数中。

mySwiper.addCallback('SlideChangeStart', function(swiper){

alert('Hello 2');

})

你会发觉在过渡动画开始时弹出“Hello 1” 以及“Hello 2“，该种方式下addCallback方法需要注意该回调函数名不包含”on“。

解除（fire）callback 函数语句：

mySwiper.fireCallback('SlideChangEnd',mySwiper);

移除（remove）callbacks:

mySwiper.removeCallback('SlideChangEnd');

相关文章