iScroll5 API速查隨記

轉自：http://www.cnblogs.com/sunshq/p/4119055.html

版本

針對iScroll的優化。為了達到更高的效能，iScroll分為了多個版本。你可以選擇最適合你的版本。
目前我們有以下版本：

iscroll.js，這個版本是常規應用的指令碼。它包含大多數常用的功能，有很高的效能和很小的體積。
iscroll-lite.js，精簡版本。它不支援快速跳躍，滾動條，滑鼠滾輪，快捷鍵繫結。但如果你所需要的是滾動(特別是在移動平臺) iScroll 精簡版是又小又快的解決方案。
iscroll-probe.js，探查當前滾動位置是一個要求很高的任務,這就是為什麼我決定建立一個專門的版本。如果你需要知道滾動位置在任何給定的時間,這是iScroll給你的。（我正在做更多的測試,這可能最終在常規iscroll.js指令碼，請留意）。

iscroll-zoom.js，在標準滾動功能上增加縮放功能。
iscroll-infinite.js，可以做無限快取的滾動。處理很長的列表的元素為移動裝置並非易事。 iScroll infinite版本使用快取機制,允許你滾動一個潛在的無限數量的元素。

入門

IScroll是一個類，每個需要使用滾動功能的區域均要進行初始化。每個頁面上的iScroll例項數目在裝置的CPU和記憶體能承受的範圍內是沒有限制的。

儘可能保持DOM結構的簡潔。iScroll使用硬體合成層但是有一個限制硬體可以處理的元素。
最佳的HTML結構如下：

<div id="wrapper"> <ul> <li>...</li> <li>...</li> ... </ul> </div>

iScroll作用於滾動區域的外層。在上面的例子中，UL元素能進行滾動。只有容器元素的第一個子元素能進行滾動，其他子元素完全被忽略。

最基本的指令碼初始化的方式如下：

<script type="text/javascript"> var myScroll = new IScroll('#wrapper'); </script>

第一個引數可以是滾動容器元素的DOM選擇器字串，也可以是滾動容器元素的引用物件。下面是一個有效的語法：

var wrapper = document.getElementById('wrapper'); var myScroll = new IScroll(wrapper);

所以基本上你要麼直接傳遞元素，要麼傳遞一個querySelector字串。因此可以使用css名稱代替ID去選擇一個滾動器容器,如下:

var myScroll = new IScroll('.wrapper');

注意，iScroll使用的是querySelector 而不是 querySelectorAll，所以iScroll只會作用到選擇器選中元素的第一個。如果你需要對多個物件使用iScroll，你需要構建自己的迴圈機制。

初始化

當DOM準備完成後iScroll需要被初始化。最保險的方式是在window的onload事件中啟動它。
在DOMContentLoaded事件中或者inline initialization中做也可以，需要記住的是指令碼需要知道滾動區域的高度和寬度。如果你有一些圖片在滾動區域導致不能立馬獲取區域的高度和寬度，iScroll的滾動尺寸有可能會錯誤。

為滾動起容器增加position:relative或者absolute樣式。這將解決大多數滾動器容器大小計算不正確的問題。
綜上所述，最小的iScroll配置如下：

 <head> ... <script type="text/javascript" src="iscroll.js"></script> <script type="text/javascript"> var myScroll; function loaded() { myScroll = new IScroll('#wrapper'); } </script> </head> ... <body onload="loaded()"> <div id="wrapper"> <ul> <li>...</li> <li>...</li> ... </ul> </div> </body>

如果你有一個複雜的DOM結構，最好在onload事件之後適當的延遲，再去初始化iScroll。最好給瀏覽器100或者200毫秒的間隙再去初始化iScroll。

配置

在iScroll初始化階段可以通過建構函式的第二個引數配置它。

var myScroll = new IScroll('#wrapper', { mouseWheel: true, scrollbars: true });

上面的例子示例了在iScroll初始化時開啟滑鼠滾輪支援和滾動條支援。

在初始化後你可以通過options物件訪問標準化值。例如： js console.dir(myScroll.options);
上面的語句將返回myScroll例項的配置資訊。所謂的標準化意味著如果你設定useTransform:true，但是瀏覽器並不支援CSS
transforms，那麼useTransform屬性值將為false。

理解核心

iScroll使用基於裝置和瀏覽器效能的各種技術來進行滾動。通常不需要你來配置引擎，iScroll會為你選擇最佳的方式。

儘管如此，理解iScroll工作機制和了解如何去配置他們也是很重要的。

options.useTransform

預設情況下引擎會使用CSStransform屬性。如果現在還是2007年，那麼可以設定這個屬性為false，這就是說：引擎將使用top/left屬性來進行滾動。
這個屬性在滾動器感知到Flash，iframe或者視訊外掛內容時會有用，但是需要注意：效能會有極大的損耗。
預設值：true

options.useTransition

iScroll使用CSS transition來實現動畫效果（動量和彈力）。如果設定為false，那麼將使用requestAnimationFrame代替。
在現在瀏覽器中這兩者之間的差異並不明顯。在老的裝置上transitions執行得更好。
預設值：true

options.HWCompositing

這個選項嘗試使用translateZ(0)來把滾動器附加到硬體層，以此來改變CSS屬性。在移動裝置上這將提高效能，但在有些情況下,你可能想要禁用它(特別是如果你有太多的元素和硬體效能跟不上)。
預設值：true

如果不確定iScroll的最優配置。從效能角度出發，上面的所有選項應該設定為true。（或者更好的方式，讓他們自動設定屬性為true）。你可以嘗試這配置他們，但是要小心記憶體洩漏。

基本功能

options.bounce

當滾動器到達容器邊界時他將執行一個小反彈動畫。在老的或者效能低的裝置上禁用反彈對實現平滑的滾動有幫助。
預設值：true

options.click

為了重寫原生滾動條，iScroll禁止了一些預設的瀏覽器行為，比如滑鼠的點選。如果你想你的應用程式響應click事件，那麼該設定次屬性為true。請注意，建議使用自定義的tap 事件來代替它（見下面）。
預設屬性：false

options.disableMouse

options.disablePointer

options.disableTouch

預設情況下，iScroll監聽所有的指標事件，並且對這些事件中第一個被觸發的做出反應。這看上去是浪費資源，但是在大量的瀏覽器/裝置上相容，特定的事件偵測證明是無效的，所以listen-to-all是一個安全的做法。

如果你有一種裝置偵測的內部機制，或者你知道你的指令碼將在什麼地方執行，你可以把你不需要的事件禁用（滑鼠，指標或者觸控事件）。
下面的例子是禁用滑鼠和指標事件：

var myScroll = new IScroll('#wrapper', { disableMouse: true, disablePointer: true });

預設值：false

options.eventPassthrough

有些時候你想保留原生縱向的滾動條但想為橫向滾動條增加iScroll功能（比如走馬燈）。設定這個屬性為true並且iScroll區域只將影響橫向滾動，縱向滾動將滾動整個頁面。

在移動裝置上訪問event passthrough demo。注意，這個值也可以設定為horizontal，其作用和上面介紹的相反（橫向滾動條保持原生，縱向滾動條使用iScroll）。

options.freeScroll

此屬性針對於兩個兩個緯度的滾動條（當你需要橫向和縱向滾動條）。通常情況下你開始滾動一個方向上的滾動條，另外一個方向上會被鎖定不動。有些時候，你需要無約束的移動（橫向和縱向可以同時響應），在這樣的情況下此屬性需要設定為true。請參考 2D scroll demo。
預設值：false

options.keyBindings

此屬性為true時啟用鍵盤（和遠端控制）繫結。請參考下面的Key bindings內容。
預設值：false

options.invertWheelDirection

當滑鼠滾輪支援啟用後，在有些情況下需要反轉滾動的方向。（比如，滑鼠滾輪向下滾動條向上，反之亦然）。
預設值：false

options.momentum

在使用者快速觸控式螢幕幕時，你可以開/關勢能動畫。關閉此功能將大幅度提升效能。
預設值：true

options.mouseWheel

偵聽滑鼠滾輪事件。
預設值：false

options.preventDefault

當事件觸發時師傅執行preventDefault()。此屬性應該設定為true，除非你真的知道你需要怎麼做。
請參考下面的Advanced features中的preventDefaultException，可以獲取更多控制preventDefault行為的資訊。
預設值：true

options.scrollbars

是否顯示為預設的滾動條。更多資訊請檢視Scrollbar
預設值：false

options.scrollX

options.scrollY

預設情況下只有縱向滾動條可以使用。如果你需要使用橫向滾動條，需要將scrollX 屬性值設定為 true。請參考示例horizontal demo。

也可以參考freeScroll選項。

預設值：scrollX: false，scrollY: true

注意屬性 scrollX/Y: true 與overflow: auto有相同的效果。設定一個方向上的值為 false 可以節省一些檢測的時間和CPU的計算週期。

options.startX

options.startY

預設情況下iScroll從0, 0 (top left)位置開始，通過此屬性可以讓滾動條從不同的位置開始滾動。
預設值：0

options.tap

設定此屬性為true，當滾動區域被點選或者觸控但並沒有滾動時，可以讓iScroll丟擲一個自定義的tap事件。
這是處理與可以點選元素之間的使用者互動的建議方式。偵聽tap事件和偵聽標準事件的方式一致。示例如下：

element.addEventListener('tap', doSomething, false); \\ Native $('#element').on('tap', doSomething); \\ jQuery

你可以通過傳遞一個字串來自定義事件名稱。比如：

tap: 'myCustomTapEvent'

在這個示例裡你應該偵聽名為myCustomTapEvent的事件。
預設值：false