本文分享自 http://www.cnblogs.com/scavengers/p/3760449.html
---------------------------華麗的分割線----------------------------------
最近使用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="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, //設置動畫持續時間500ms 12 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 //復制、插入Slide 14 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 //移除最后一個slide 20 mySwiper.removeLastSlide() 21 22 //移除第二個slide 23 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的html 35 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" ，因為這樣做可能產生死循環。 |