Swiper 中文API手冊（share）

---------------------------華麗的分割線---------------------------------- 

最近使用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:

其中引用的檔案名以下載下傳的為準。

3、使用下面的HTML布局

4、打開下載下傳的檔案中的idangerous.swiper.css，設定Swiper's的寬度以及高度（在檔案的末尾）

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

5、初始化Swiper 在文檔開始處，（或在視窗加載時）

API:

new Swiper（container,options）

container: 字元串要求，Swiper's容器的css選擇器。在上面的HTML代碼中就必須等于“.swiper-container”;

options:-對象，可選擇的。Swiper參數，詳情見下：  

用法：

傳回擁有衆多有用函數（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（參數）

Type(類型)

Default Value（預設值

Example（例子）

Description（說明）

speed

number

300

600

slides滑塊動畫之間的持續時間（機關ms）

eventTarget

string

'wrapper'

'container'

swipers事件對象，預設狀态下所有的觸控事件隻能用于wrapper。如若需要其他元素包含在container内以及使用swipers,那麼可以使用'container'. 2.4.2版本新增

autoplay

5000

-

過渡延遲時間（機關ms），參數沒有指定的情況下，不生效，（補充：當使用者操作後autoplay失效）

autoplayDisableOnInteraction

boolean

true

false

當設定為false時，使用者操作之後（swipes,arrow以及pagination 點選）autoplay不會被禁掉，使用者操作之後每次都會重新啟動autoplay。

autoplayStopOnLast

設定為false後autoplay在最後一個塊下失效（在沒有設定loop的情況下）

mode

'horizontal'

'vertical'

slides滑動方式，水準或垂直

loop

true 為loop模式生效

loopAdditionalSlides

2

loop模式下slides數量增加個數

loopedSlides

1

在loop模式下使用slidesPerview:'auto',還需使用該參數設定所要用到的loop個數

slidesPerView

or 'auto'

4

旋轉模式下，設定slider's容器能夠同時顯示的slides數量。另外，支援'auto'值，會根據容器container的寬度調整slides數目。‘auto’不相容loop模式

slidesPerViewFit

僅當已設定了slidesPerView:'auto'，以及當slides的寬度大于容器，該參數生效。預設為true然後寬度大的slide 過渡時會劃分為邊緣的兩部分。為false時，slide transition 會劃分為比容器container大的多個slides

slidesPerGroup

定義slides的數量多少為一組，在旋轉模式下有效。（carousel mode）

calculateHeight 

當值為true時，Swiper根據slides内容計算容器高度。響應式布局中或不知道slides高度時十分有用（就像響應式的圖檔）

roundLengths

值為true時，Swiper會四舍五入寬度和高度，在響應式的滑塊中包含誤差時十分有用。

cssWidthAndHeight 

false 

值為true以及Swiper中的container，wrapper和slides沒有高度

updateFormElements

當所有的内嵌圖像（img标簽）加載完成後Swiper會重新初始化。

watchActiveIndex

如果啟用觸屏事件期間會重新動态計算活動塊的索引。

visiblilityFullfit

如果啟用，僅有“可視”的slides會最後适應容器的大小

autoResize

值為false時，視窗尺寸改變時，禁掉slides自适應

DOManimation

在不支援css transitions(IE7-9)的浏覽器上是否使用自定義的DOM動畫

resistance

boolean or "100%"

true 

值為false時禁用resistant bounds（抵抗反彈）,設定為‘100%'時啟用resistant（抵抗）模式

noSwiping

值為true時，當swiper新增類”noSwipingClass“的滑動塊時，禁掉該元素的滑動。

preventLinks

啟用時當碰觸滑塊（slides）時禁止<a>标簽連結

preventLinksPropagation

如滑動過程中需要跟preventLinks一起禁用stopPropagation，設定值為true

initialSlide

初始塊（頁面）的索引

useCSS3Transforms

值為false時禁用css3 transforms（減少記憶體，提高性能，同時也降低了美觀）,同時使用wrapper的left/top屬性代替。

自由模式與滑塊容器（Free Mode and Scroll Container)

Description（說明

freeMode

若為真slide坐标不固定

freeModeFluid

若為真，釋放滑塊之後仍會滑動一小會

scrollContainer

設定為真時，讓Swiper看上去像滑動區（scrollable area）

momentumRatio

設定的值越大，當釋放滑塊時的動量距離越大

momentumBounce

false時禁用自由模式下的（free mode）動量彈性

momentumBounceRatio

值越大産生的動量彈性（momentum bounce）效果越明顯

塊（slides）偏移

centeredSlides

若為真，那麼活動塊會居中，而非預設狀态下的居左

offsetPxBefore

100

指定slides與wrapper左邊框的偏移量

offsetPxAfter

指定slides與wrapper右邊框的偏移量

offsetSlidesBefore

滑塊slides與wrapper左邊框的偏移量等于等于指定滑塊slides個數的寬度。這在響應式布局中而你又不知道slides寬度時，将十分有用。

offsetSlidesAfter

滑塊slides與wrapper右邊框的偏移量等于等于指定滑塊slides個數的寬度。這在響應式布局中而你又不知道slides寬度時，将十分有用。

觸屏/滑鼠事件效應（Touch/mouse interactions ）

touchRatio

0.8

觸屏比率

simulateTouch

true,Swiper接受滑鼠事件時與觸屏事件相似。（單擊以及拖曳滑塊）

onlyExternal

值為true時，隻能使用擴充API函數内的swipeRight 或swiperLeft改變slides滑動，其他失效。正如例子裡的tabs切換十分有用

followFinger

值為false時，僅當你釋放slide時才會滑動，當你用手指按住滑塊它不會動。

grabCursor

該選項給Swiper使用者提供小小的貼心應用，值為true時，光标在Swiper上時成手掌狀。

shortSwipes

值為false時，禁用short swipes

longSwipesRatid

0.5

0.3

Swiper 中到上/下滑塊的觸發率

moveStartThreshold

滑動的臨界值，臨界值機關為px，如果觸屏距離小于該值滑塊不會運動。

Navigation

keyboardControl

值為true時，水準模式下，能使用鍵盤左右方向鍵滑動，垂直模式下能使用上下方向鍵滑動

mousewheelControl

值為true時，能夠使用滑鼠滑輪滑動swiper

mousewheelControlForceToAxis

值為真時，滑鼠輪滑會改變軸向，是以水準模式下的滑鼠滑輪隻作用于水準滑鼠滑塊，垂直的作用于垂直模式。

Pagination（分頁器）(訓示器)

pagination

string or HTML Element

'.my-pagination'

css選擇器中的分頁。或者HTML元素内的分頁元素

paginaClickable

值為真時，當單擊訓示器時會執行過渡動畫到目标slide

paginationAsRange

為真時，跟可見塊相關的訓示器按鈕會新增css類。當使用slidesPerview超過1時會十分有用。

createPagination

值為真時，Swiper會在slider内生成與slides數量相同的SPAN标簽。所有這些生成的span标簽都在pagination容器内。每一個span标簽都有一個”swiper-pagination-switch“類名，活動的span（及目前slide下的）有一個為”swiper-active-switch’的類名，對于這些使用樣式十分有用。

命名空間namespace

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類名。。。

'swiper-slide-visible'

'my-visible-slide'

Swiper内可視塊的css類名。。。

slideElement

'div'

'li'

使用單一滑塊的标簽

noSwipingClass

'swiper-no-swiping'

'stop-swiping'

html元素使用的類名，當noSwiping參數設定為true時，用于禁止滑動

paginationElement

'span'

使用唯一訓示按鈕的标簽

paginatinElementClass

'swiper-pagination-switch'

'my-switch'

使用多個訓示按鈕的類名

paginationActiveClass

'swiper-active-switch'

'my-active-switch'

目前活動訓示按鈕的類名

paginationVisibleClass

'swiper-visible-switch'

'my-visible-switch'

可見訓示按鈕的類名

回調函數（Callbacks）

queueStatCallbacks

設定為true時，‘slideChangeStart’回調函數入隊，是以在快速滑動過程中回調函數隻被調用一次。

queueEndCallbacks

設定為true時，‘slideChangeEnd’回調函數入隊，是以在快速滑動結束後回調函數隻被調用一次。

onFirstInit

funciton

function(swiper) 

{ 

//執行代碼 

}

回調函數，首次初始化後馬上執行

onInit

function

function(swiper){ 

//執行代碼

回調函數，在其他所有的初始化/再初始化後馬上執行

onSwiperCreated

回調函數，當Swiper初始化完成，loop，pagination，等其他參數或方法生成之後執行

onTouchStart

回調函數，當碰觸到slider時馬上執行

onTouchMove

回調函數，當碰觸slider到釋放期間執行。

onTouchEnd

回調函數，當釋放slider時執行

onSlideReset

回調函數，釋放滑塊之後，滑塊将要滑到目前活動的slide時執行。freeMode模式下不生效。

onSlideChangeStart

回調函數，當動畫開始過渡到另一slide時執行，即動畫開始時執行。freeMode模式下不生效。

onSlideChangeEnd

回調函數，過渡動畫結束後執行，即滑塊活動停止後執行。freeMode模式下不生效。

onSlideNext

回調函數，與onSlideChangeStart相似，但該函數隻能在滑向下一slide開始時生效

onSlidePrev

回調函數，與onSlideChangeStart相似，但該函數隻能在滑向上一slide開始時生效

onSlideTouch

回調函數，當觸碰事件發生後生效。與onToucStart相似，不過該函數會傳回.clickedSlide和.clickedSlideIndex的值

onImageReady

回調函數，所有内置圖像加載完成後執行，同時“updateOmImagesReady”需設定為“true’

onMomentumBounce

function 

回調函數，執行于動量反彈（momentum bounce）過程中

onResistanceBefore

function(swiper,p){ 

回調函數，執行于negative resistance過程中。p-傳回抵抗距離。

onResistanceAfter

回調函數，執行于positive resistance過程中。p-傳回抵抗距離。

onSetWrapperTransition

function(swiper,duration){

回調函數，每次當Swiper開始動畫時執行

onSetWrapperTransform

function(swiper,transform){

回調函數，swiper的容器wrapper改變其坐标時執行。傳回帶目前transform 的偏移量的對象。

Example

以下需要引用jQuery檔案

Callbacks API

從Swiper2.4版本開始增加了一些回調函數，現在添加一些函數到上面。

當初始化Swiper時，舊版本指定回調函數的方式：

新版本中能夠實作無需完全重寫onSlideChangeStart參數，可以添加新函數到回調函數中。

你會發覺在過渡動畫開始時彈出“Hello 1” 以及“Hello 2“，該種方式下addCallback方法需要注意該回調函數名不包含”on“。

解除（fire）callback 函數語句：

移除（remove）callbacks:

Slides API

Swiper提供強大的Slides API，能夠動态生成/删除/操作Slides（滑塊）

Slide 執行個體

這個執行個體是簡單的HTML元素但擴充了非常有用的方法。

下面的例子變量mySwiper包含了屬性和方法的Swiper對象。

通過調用一下方法，你能生成Swiper滑塊執行個體：

mySwiper.createSlide(html,slideClassList,element),其中：

html(string[字元型],required[必需的])-生成的滑塊的HTML元素的内容

slideClassList(stirng[字元型],optional[可選的])- 建立類”class“屬性。預設值為"swiper-slide "

element(string[字元型],optional[可選的])-建立滑塊的HTML标簽，預設值為"div"

"newSlide"變量包含在建立Slide執行個體之後,但如今還在記憶體中，并不在slider中。為了将其添加到slider中，能夠使用一下鍊式方法有效地添加到Slide執行個體中：

newSlide.append()-添加slide到slider中的最後一個位置。傳回Slide執行個體

newSlide.prepend()-添加slide到slider中的第一個位置。傳回Slide執行個體

newSlide.remove()-移除slide

newSlide.getWidth()-傳回slide寬度

newSlide.getHeight()-傳回slide高度

newSlide.getOffset()-傳回包含滑塊left、top偏移量的對象

newSlide.insertAfter(index)[index-number]-插入新滑塊到index索引之後。傳回Slide執行個體

newSide.clone()-複制slide到新slide執行個體。傳回新複制的Slide執行個體

還有一些有用的方法：

slide.html(innerHTMl)[innerHTMl-string]-工作方式類似于jQuery/Zepto.html()方法。如果指定innerHTML，那麼它會替代原來slide裡的inner html内容，然後方法傳回slide執行個體。

如果innerHTML沒有指定，傳回slide中inner html内容。

slide.index()-傳回slide索引

slide.isActive()傳回true如果該塊是活動的

slide.setData(name,value)[name-string]-存儲資料方法，能夠存儲所有類型變量-數組，對象，數字，字元等等

slide.getData(name)[name-string]傳回存儲的變量值

slide.data(name,value)[name-string,value-string]-儲存變量值到data-[name]屬性中

slide.data(name)[name-string]-傳回data-[name]屬性值

<a href="http://www.cnblogs.com/" target="_blank"></a>

Swiper Slides

好的，讓我們 看看swiper是如何操作存在的slides（添加/移除）

 mySwiper.slides-slides數組（slides對象）

mySwiper.appendSlide(innerHTMl,slideClassList,element)-建立新滑塊并插入到slider最後面。傳回slide執行個體：其中：

mySwiper.appendSlide(slideInstance)[slideInstance-HTMLElement]-插入到slider末尾。傳回slide執行個體

mySwiper.prependSlide(innerHTMl,slideClassList,element)-新建立slide并插入到slider首位置。傳回slide執行個體

mySwiper.prependSlide(slideInstance)[slideInstance-HTMLElement]-将slideInstance插入到slider首位置。傳回slide執行個體。

mySwiper.insertSlideAfter(index,innerHTML,slideClassList,element)-新建立slide并插入到slider指定的索引位置index。傳回slide執行個體。

mySwiper.insertSlideAfter(index,slideInstance)-将slideInstance插入到slider指定的索引位置index。傳回slide執行個體。

mySwiper.removeSlide(index)[index-numer]-移除索引為index的slide

mySwiper.removeLastSlide()-移除最後一個slide

mySwiper.removeAllSlides()-移除所有slides

mySwiper.getSlide(index)[index-number]-傳回index索引的slide

mySwiper.getLastSlide()-傳回最後一個slide

mySwiper.getFirstSlide()-傳回第一個slide

Important Notes 

重要備注 

當使用改變slides數量的方法時（例如append,prepend,remove等等），reInit()方法會被調用然後slides數量會自動重新計算。是以非常不推薦動态添加/删除slides時在"for"循環中使用"slides.length" ，因為這樣做可能産生死循環。

 本文轉自挨踢前端部落格園部落格，原文連結http://www.cnblogs.com/duanhuajian/p/4097310.html如需轉載請自行聯系原作者

@挨踢前端