iScroll 是行動裝置上最常用的自訂滾動方案之一,官網為 https://iscrolljs.com/。以下把初始化、常用參數、API 與事件整理成一份可查閱的對照說明。
iScroll 需要「一個固定高度的容器 + 內部可溢出內容」的兩層結構:
<div id="wrapper">
<ul>
<li>...</li>
<li>...</li>
</ul>
</div>
var myScroll = new IScroll('#wrapper', options);
// 實際範例:啟用滾動條並支援滑鼠滾輪
var myScroll = new IScroll('#wrapper', { mouseWheel: true, scrollbars: true });
| 參數 | 說明 | 預設 |
|---|---|---|
| options.useTransform | 是否使用 CSS3 Transform | true |
| options.useTransition | 是否使用 CSS3 Transition,否則改用 requestAnimationFrame | true |
| options.HWCompositing | 是否啟用硬體加速 | true |
| options.bounce | 是否啟用彈力動畫,關閉可提速 | true |
| 參數 | 說明 | 預設 |
|---|---|---|
| options.click | 是否啟用 click 事件,建議關閉並改用 tap | false |
| options.disableMouse / disablePointer / disableTouch | 關閉對應的事件探測;已知執行平台時開啟可提速 | false |
| options.eventPassthrough | 橫向滾動時保留系統的直向滾動 | false |
| options.freeScroll | 允許任意方向自由滾動,適合二維滾動 | false |
| options.keyBindings | 綁定鍵盤方向鍵、PageUp/Down、Home/End | false |
| options.invertWheelDirection | 反向滑鼠滾輪 | false |
| options.momentum | 是否開啟動量動畫,關閉可提速 | true |
| options.mouseWheel | 是否監聽滑鼠滾輪 | false |
| options.preventDefault | 是否阻擋瀏覽器預設行為 | true |
| options.scrollbars | 是否顯示預設滾動條 | false |
| options.scrollX / scrollY | 分別控制橫向與直向滾動,預設 X=false、Y=true | — |
| options.tap | 啟用自訂 tap 事件,可自訂事件名稱 | false |
| 參數 | 說明 | 預設 |
|---|---|---|
| options.fadeScrollbars | 滾動條是否淡出,關閉可提速 | true |
| options.interactiveScrollbars | 使用者能否拖曳滾動條 | false |
| options.resizeScrollbars | 是否固定滾動條尺寸,自訂樣式時建議開啟 | false |
| options.shrinkScrollbars | 超出邊界時是否收縮:'clip' 裁切、'scale' 等比縮放(較耗 CPU)、false 不收縮 | false |
indicators 是滾動條的底層實作,可細調:
el:指定滾動條容器,容器內的第一個元素即為指示器,可傳 DOM 或選擇器字串。ignoreBoundaries:忽略容器邊界,設為 true 可自訂滾動速度(視差效果常用)。listenX / listenY:指示器要監聽哪個方向,預設 true。speedRatioX / speedRatioY:指示器相對主滾動的速度,預設 0。fade / interactive / resize / shrink:意義同 scrollbars 的對應設定。options.probeType 需搭配 iscroll-probe.js:1 為滾動不繁忙時觸發、2 為滾動中定時觸發、3 為每滾動一像素觸發一次。
options.snap:自動分割容器,可設 true 依容器尺寸分割,或傳入元素;常用於輪播效果。options.zoom:是否啟用縮放,建議搭配 iscroll-zoom.js。若放大後模糊,可把原始容器放大兩倍再以 scale(0.5) 呈現。options.zoomMax / zoomMin / startZoom:預設 4 / 1 / 1。options.wheelAction:設為 'zoom' 可用滾輪縮放。bindToWrapper:游標或觸控離開容器時是否停止滾動,預設 false。bounceEasing:彈力緩動,預設值有 'quadratic'、'circular'、'back'、'bounce'、'elastic'(後兩者無法用 CSS3 呈現),也可自訂 {style:'cubic-bezier(0,0,1,1)', fn:function(k){return k;}}。bounceTime:彈力動畫毫秒數,預設 600。deceleration:動量衰減,數值越大減速越快,建議不超過 0.01,預設 0.0006。preventDefaultException:指定哪些元素不阻擋預設行為,預設 {tagName:/^(INPUT|TEXTAREA|BUTTON|SELECT)$/}。resizePolling:視窗重繪時重新計算的間隔,預設 60。scrollTo(x, y, time, easing):滾動到絕對座標,easing 可為 quadratic、circular、back、bounce、elastic,例如 myScroll.scrollTo(0, -100, 1000, IScroll.utils.ease.elastic);scrollBy(x, y, time, easing):以目前位置為基準做相對位移。scrollToElement(el, time, offsetX, offsetY, easing):滾動到指定元素,offset 設為 true 會對齊畫面中央。goToPage(x, y, time, easing):搭配 snap 使用,跳到橫向/直向的某一頁。next() / prev():上一頁、下一頁,同樣搭配 snap。zoom(scale, x, y, time):縮放容器。refresh():內容變動後重新計算,這一步最容易忘記。destroy():銷毀實例釋放資源。beforeScrollStart(觸控但尚未開始滾動)、scrollCancel、scrollStart、scroll、scrollEnd、flick(左右輕掃)、zoomStart、zoomEnd。
myScroll = new IScroll('#wrapper');
myScroll.on('scrollEnd', doSomething);
myScroll.x / myScroll.y:目前位置。myScroll.directionX / directionY:上次滾動方向(-1 下/右、0 未變、1 上/左)。myScroll.currentPage:目前的 snap 資訊。myScroll.maxScrollX / maxScrollY:滾到底時的 x / y 值。