title: IScroll-5的文檔
date: 2017-07-03 11:10:40
tags: javascript常用插件

結(jié)構(gòu)

使用IScroll這個腳本庫時诈茧，DOM樹的結(jié)構(gòu)要足夠簡單，移除不必要的標簽倚评，盡量避免過多的標簽嵌套使用忆畅。

最優(yōu)的使用iScroll的結(jié)構(gòu)如下所示

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

只有wrapper里的第一個子元素才可以滾動挎扰，如果你想要更多的元素可以滾動佛玄，那么你可以試試下面的這種寫法

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

實例化IScroll

<script>
  var myscroll=new IScroll("wrapper",{hScrollbar:false, vScrollbar:false});
</script>

第一個參數(shù)是滾動元素外層容器的選擇器字符串，也可以是元素對象扯夭。

注意鳍贾，IScroll使用的是querySelector 而不是 querySelectorAll，所以IScroll只會作用到選擇器選中元素的第一個勉抓。如果你需要對多個對象使用IScroll贾漏，你需要構(gòu)建自己的循環(huán)機制藕筋。

第二個參數(shù)是一個對象纵散。

在初始化之后隐圾，可以通過options對象訪問標準化值。如果設(shè)置了瀏覽器不支持的屬性暇藏，那么即使在初始化時設(shè)置為true蜜笤，在這里也會顯示為false。

console.log(myScroll.options);

IScroll的核心參數(shù)

options.useTransform

默認值是true

如果設(shè)置為false盐碱，將使用top/left屬性這種老的方式進行滾動沪伙。

這個屬性在滾動器感知到Flash县好，iframe或者視頻插件內(nèi)容時會有用围橡，但是需要注意：性能會有極大的損耗。

options.useTransition

默認是true

使用css的transition實現(xiàn)動畫效果(動量和彈力)缕贡，如果設(shè)置為false翁授，將使用requestAnimationFrame代替晾咪，在舊設(shè)備上transition執(zhí)行的更好

options.HWCompositing

默認是為true

這個選項嘗試使用translate(0)來把滾動器附加到硬件層，以此來改變css屬性谍倦，在移動設(shè)備上將提高性能

如果不確定IScroll的最優(yōu)配置，從性能角度出發(fā)减途，上面的所有選項都應(yīng)該設(shè)置為true

IScroll的基本參數(shù)

options.bounce

默認值true

滾動到邊界反彈動畫曹洽，在舊的設(shè)備上禁用對實現(xiàn)平滑滾動有幫助辽剧。

options.click

默認值是false

為了重寫原生滾動條，iScroll禁止了一些默認的瀏覽器行為偷崩，比如鼠標的點擊撞羽。如果你想你的應(yīng)用程序響應(yīng)click事件，那么該設(shè)置次屬性為true诀紊。

options.disableMouse、options.disablePointer笤喳、options.disableTouch

默認值是false

可以把你不需要的事件禁用（鼠標碌宴，指針、觸摸事件）呜象，設(shè)置為true是禁用膳凝。

options.eventPassthrough

有些時候你想保留原生縱向滾動條蹬音，但是想為橫向滾動條增加IScroll功能子姜。就可設(shè)置為true。

實現(xiàn)橫向滾動的代碼如下：

js部分

var myScroll = new IScroll('#wrapper', {
    eventPassthrough: true,
    scrollX: true, 
    scrollY: false
});

html部分

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

css部分

#wrapper {
    width: 100%;
    background: #eeeeee;
    overflow: hidden;
}

#scroller {
    z-index: 1;
    width: 1010px;
}

#scroller li {
    width: 100px;
    float: left;
    font-size: 14px;
    overflow: hidden;
    text-align: center;
}

options.freeScroll

默認值是false

可以橫軸和縱軸同時滾動牧抽，需要設(shè)置為true。代碼實例如下：

js部分

myScroll = new IScroll('#wrapper', {
    scrollX: true,
    freeScroll: true
});

html部分

<div id="wrapper">
    <div id="scroller">
        <p>111111111111111111111111111111111111</p>
        ......
    </div>
</div>

css部分

#wrapper {
    position: relative;
    height: 200px;
    width: 200px;
    background: #666;
    overflow: hidden;
}

#scroller {
    position: absolute;
    z-index: 2;
    width: 2000px;
    background: #fff;
}

p {
    font-size: 16px;
    line-height: 1;
    overflow: hidden;
}

options.keyBindings

默認值false

設(shè)置為true時可以激活鍵盤綁定遥赚。

options.invertWheelDirection

默認為false

當鼠標滾輪支持激活后凫佛，在有些情況下需要反轉(zhuǎn)滾動的方向。（比如晨炕，鼠標滾輪向下滾動條向上）毫炉。

options.momentum

默認值true

在用戶快速觸摸屏幕時瓮栗，你可以開/關(guān)勢能動畫瞄勾。關(guān)閉此功能將大幅度提升性能。

options.mouseWheel

默認值false

是否監(jiān)聽鼠標滾輪事件愿阐。

options.preventDefault

默認值true

當事件觸發(fā)時是否執(zhí)行preventDefault()趾疚。此屬性應(yīng)該設(shè)置為true盗蟆。

options.preventDefault

默認值false

是否顯示為默認的滾動條。

options.scrollX喳资、options.scrollY

scrollX默認值false，scrollY默認值true

scrollX為是否進行橫向滾動鲜滩，scrollY為是否進行縱向滾動

options.startX、options.startY

默認值0

默認情況下iScroll從0, 0 (top left)00位置開始榜聂，通過此屬性可以讓滾動條從不同的位置開始滾動嗓蘑。

options.tap

默認false

設(shè)置此屬性為true，當滾動區(qū)域被點擊或者觸摸但并沒有滾動時豌汇，可以讓iScroll拋出一個自定義的tap事件泄隔。

滾動條

滾動條不只是像名字所表達的意義一樣佛嬉，在內(nèi)部它們是作為indicators的引用。

一個指示器偵聽滾動條的位置并且現(xiàn)實它在全局中的位置斜做，但是它可以做更多的事情湾揽。

options.scrollbars

激活滾動條，代碼如下：

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

options.fadeScrollbars

默認值false

設(shè)置為true則滾動條使用淡入淡出的方式，不適用淡入淡出比較節(jié)省資源艳狐。

options.interactiveScrollbars

默認值false

設(shè)置為true可以讓滾動條能拖動

options.resizeScrollbars

默認值true

滾動條尺寸改變基于容器和滾動區(qū)域的寬/高之間的比例皿桑。此屬性設(shè)置為false讓滾動條固定大小诲侮。這可能有助于自定義滾動條樣式

options.shrinkScrollbars

有效值是clip和scale

clip是移動指示器到它容器的外面，效果就是滾動條收縮起來刮便，簡單的移動到屏幕以外的區(qū)域绽慈。屬性設(shè)置為此值后將大大的提升整個iScroll的性能辈毯。

scale關(guān)閉屬性useTransition谆沃，之后所有的動畫效果將使用requestAnimationFrame實現(xiàn)仪芒。指示器實際上有各種尺寸，并且最終的效果最好据沈。

如果頁面在多種設(shè)備上運行最好使用scale铆隘，在舊的設(shè)備上應(yīng)該設(shè)置為clip膀钠。

滾動條樣式

如果不喜歡默認的滾動條樣式，可以自定義融击。

第一步是設(shè)置選項scrollbars的值為custom雳窟。

以下內(nèi)容是自定義滾動條需要設(shè)置的css類名

.iScrollHorizontalScrollbar

這個樣式應(yīng)用到橫向滾動條的容器封救。這個元素實際上承載了滾動條指示器。

.iScrollVerticalScrollbar

和上面的樣式類似鹅士，只不過適用于縱向滾動條容器惩坑。

.iScrollIndicator

真正的滾動條指示器。

.iScrollBothScrollbars

這個樣式將在雙向滾動條顯示的情況下被加載到容器元素上趾痘。通常情況下其中一個（橫向或者縱向）是可見的永票。

指示器

上面所有關(guān)于滾動條的選項實際上是包裝了一個底層的選項indicators。它看起來或多或少像這樣

var myScroll = new IScroll('#wrapper', {
    indicators: {
        el: [element|element selector]
        fade: false,
        ignoreBoundaries: false,
        interactive: false,
        listenX: true,
        listenY: true,
        resize: true,
        shrink: false,
        speedRatioX: 0,
        speedRatioY: 0,
    }
});

options.indicators.el

這是一個強制性的參數(shù)艰赞，它保留了指向滾動條容器元素的引用肚吏，容器里的第一個子元素就是指示器罚攀，而且滾動條可以在文檔的任何地方，它不需要在滾動條包裝器內(nèi)杯瞻。

格式如下：

indicators: {
    el: document.getElementById('indicator')
}

或者

indicators: {
    el: '#indicator'
}

options.indicators.ignoreBoundaries

默認值false

這個屬性告訴指示器忽略它容器所帶來的邊界炫掐，比如想讓指示器是滾動條速度的兩倍募胃，指示器將很快到達它的結(jié)尾，這個屬性被用在視差滾動检疫。

options.indicators.listenX祷嘶、options.indicators.listenY

默認值true

指示器的橫向和縱向被偵聽≈蛞辏可以設(shè)置一個或者都設(shè)置

options.indicators.speedRatioX嘉汰、options.indicators.speedRatioY

默認值0

指示器移動的速度和主要滾動條大小的關(guān)系郑现，默認情況下是設(shè)置為自動荧降《浣耄基本不需要改變的參數(shù)。

options.indicators.fade废累、options.indicators.interactive、options.indicators.resize日缨、options.indicators.shrink

這幾個選項和已經(jīng)介紹過的滾動條中的一樣掖看，可以參考下面這個案例

js部分

myScroll = new IScroll('#wrapper', {
    startX: -359,   // 初始位置
    startY: -85,
    scrollY: true,  // 橫向縱向可同時滾動
    scrollX: true,
    freeScroll: true,   
    mouseWheel: true,
    indicators: {       
        el: document.getElementById('minimap'),    // 指向滾動條容器元素的引用哎壳，容器里的第一個子元素就是指示器
        interactive: true       // 讓指示器可滾動
    }
});

html部分

<div id="wrapper">
    <div id="scroller">
    </div>
</div>
<div id="minimap">
    <div id="minimap-indicator">
    </div>
</div>

css部分

#wrapper {
    position: absolute;
    z-index: 1;
    width: 235px;
    height: 321px;
    top: 0;
    left: 0;
    background: #555;
    overflow: hidden;
}
#scroller {
    position: absolute;
    z-index: 1;
    width: 797px;
    height: 1087px;
    background: url(ermine.jpg);
}
#minimap {
    position: absolute;
    z-index: 1;
    width: 235px;
    height: 321px;
    background: url(ermine.jpg);
    background-size: 235px 321px;
    top: 0px;
    left: 245px;
}
#minimap-indicator {
    position: absolute;
    z-index: 1;
    border: 1px solid #fe0;
    box-shadow: 0 0 5px #000;
    background: rgba(255,255,255,0.15);
}

視差滾動

視差滾動時指示器的一個功能归榕，指示器是一個遵循主滾動條移動和動畫的層。增加這個功能就可以創(chuàng)建任意數(shù)量的指示器和視差滾動外里。

js部分

myScroll = new IScroll('#wrapper', {
    mouseWheel: true,
    indicators: [{
        el: document.getElementById('starfield1'),
        resize: false,
        ignoreBoundaries: true,
        speedRatioY: 0.4
    }, {
        el: document.getElementById('starfield2'),
        resize: false,
        ignoreBoundaries: true,
        speedRatioY: 0.2
    }]
});

html部分

<div id="wrapper">
    <div id="scroller">
    </div>
</div>
<div id="starfield1" class="starfield">
    <div id="stars1"></div>
</div>
<div id="starfield2" class="starfield">
    <div id="stars2"></div>
</div>

css部分

#wrapper {
    position: absolute;
    z-index: 3;
    width: 100%;
    top: 0;
    left: 0;
    bottom: 0;
    overflow: hidden;
}

#scroller {
    position: absolute;
    z-index: 3;
    width: 100%;
    height: 4000px;
    overflow: hidden;
    background: url(galaxies1.png);
}

#starfield1 {
    z-index: 2;
}

.starfield {
    position: absolute;
    width: 100%;
    top: 0;
    left: 0;
    bottom: 0;
    overflow: hidden;
}

.starfield div {
    position: absolute;
    width: 100%;
    overflow: hidden;
}

#stars1 {
    z-index: 2;
    height: 3000px;
    background: url(galaxies2.png);
}

#stars2 {
    z-index: 1;
    height: 2000px;
    background: url(stars.jpg);
}

滾動的接口

可以通過下面的方法滾動到指定位置

scrollTo(x, y, time, easing)

初始化IScroll之后會創(chuàng)建一個myScroll實例(名字是自己定義的變量)级乐，可以通過myScroll.scrollTo(0, -100)滾動到任意位置风科。因為左上角永遠是0乞旦，所以向下滾動一定是負數(shù)

參數(shù)time和easing是可選項，他們控制滾動周期（毫秒）和動畫的擦除效果故痊。動畫擦除對象是IScroll.utils.ease玖姑，可擦除動畫類型有quadratic, circular, back, bounce, elastic焰络。

示例：myScroll.scrollTo(0, -100, 1000, IScroll.utils.ease.elastic);

scrollBy(x, y, time, easing)

和上面一個方法類似，但是可以傳遞X和Y的值從當前位置進行滾動甜孤。

myScroll.scrollBy(0, -10)會在當前位置向下滾動10個像素。

scrollToElement(el, time, offsetX, offsetY, easing)

在這個方法中只有一個強制的參數(shù)就是el茉稠。傳遞一個元素或者一個選擇器把夸，IScroll將嘗試滾動到這個元素的左上角位置扎即。

time是可選項，用于設(shè)置動畫周期各拷。

offsetX 和 offsetY定義像素級的偏移量闷营，如果把這兩個參數(shù)設(shè)置為true傻盟，元素將會位于屏幕的中間。

easing和之前的一樣规哲。

對齊

iScroll能對齊到固定的位置和元素诽表。

options.snap

按照頁面容器大小自動分割滾動條

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

也可以設(shè)置滾動條將要對齊的元素的選擇器

var myScroll = new IScroll('#wrapper', {
    snap: 'li'
});

goToPage(x, y, time, easing)

x和y呈現(xiàn)想滾動到橫向軸或者縱向軸的頁面數(shù)竿奏，如果需要咋單個緯度上使用滾動條，只需要為你不需要的軸上傳遞0值绿语。

time屬性是動畫周期候址，可選項

easing屬性是滾動到指定點使用的擦除功能類型岗仑，參照option.bounceEasing對象，可選項

在一秒鐘內(nèi)沿著橫向滾動到第10頁 myScroll.goToPage(10, 0, 1000);

縮放

為了使用縮放功能，你最好使用iscroll-zoom.js腳本舞虱。

options.zoom

默認值false

此屬性設(shè)置為true啟用縮放功能。

options.zoomMax

默認值4

最大縮放級數(shù)

options.zoomMin

默認值1

最小縮放級數(shù)

options.startZoom

默認值1

初始的縮放級數(shù)

options.wheelAction

鼠標滾輪的動作可以設(shè)置為zoom损趋，這樣在滾動滾輪時縮放操作會代替原來的滾動操作椅寺。

放大的示例：

js部分

myScroll = new IScroll('#wrapper', {
    zoom: true,
    scrollX: true,
    scrollY: true,
    mouseWheel: true,
    wheelAction: 'zoom'
});

html部分

<div id="wrapper">
    <div id="scroller">
        <p>111111111111111111111111111</p>
        ......
    </div>
</div>

css部分

#wrapper {
    position: absolute;
    z-index: 1;
    top: 50px;
    bottom: 50px;
    left: 50px;
    right: 50px;
    background: #ccc;
    overflow: hidden;
}

#scroller {
    position: absolute;
    z-index: 1;
    width: 100%;
}

zoom(scale, x, y, time)

scale是縮放因子

x 和 y是縮放關(guān)注點返帕，即縮放的中心荆萤。如果沒有指定，這個中心就是屏幕中心偏竟。

time是毫秒級別的動畫周期,可選

縮放功能使用的CSS的轉(zhuǎn)換功能敞峭。iScroll只能在支持此CSS功能的瀏覽器上執(zhí)行。
一些瀏覽器（特別是基于webkit的）采取的快照縮放區(qū)域就放在硬件合成層(比如當你申請轉(zhuǎn)換)殖蚕。該快照作為紋理的縮放區(qū)域,它幾乎不能被更新嫌褪。這意味著您的紋理將基于 scale 1 進行縮放,將導致文本和圖像模糊,清晰度低胚股。
一個簡單的解決方案是使用實際分辨率雙倍（或者三倍）裝載內(nèi)容，然后 放到一個按照scale(0.5)比例縮小的div中缨伊。這種方法大多數(shù)情況下能適用进宝。

刷新

IScroll需要知道包裝器和滾動器確切的尺寸党晋，在IScroll初始化的時候進行計算徐块，如果元素大小發(fā)生了變化胡控，需要告訴IScroll DOM發(fā)生了變化旁趟。

ajax('page.php', onCompletion);

function onCompletion () {
    // 更新DOM
    setTimeout(function () {
        myScroll.refresh();
    }, 0);
};

這里調(diào)用refresh()使用了零秒等待锡搜，如果你需要立即刷新IScroll邊界就是如此使用。當然還有其他方法可以等待頁面重繪凡傅，但零超時方式相當穩(wěn)定蛾方。

自定義事件

使用on(type, fn)方法注冊事件

myScroll = new IScroll('#wrapper');
myScroll.on('scrollEnd', doSomething);

可用的事件列表如下：

• beforeScrollStart桩砰，在用戶觸摸屏幕但還沒有開始滾動時觸發(fā)。

• scrollCancel硼莽，滾動初始化完成煮纵，但沒有執(zhí)行行疏。

• scrollStart，開始滾動

• scroll终息，內(nèi)容滾動時觸發(fā)贞让，只有在scroll-probe.js版本中有效喳张，請參考onScroll event。

• scrollEnd摸航，停止?jié)L動時觸發(fā)。

• flick凫岖，用戶打開左/右逢净。

• zoomStart爹土，開始縮放踩身。

• zoomEnd挟阻，縮放結(jié)束。

滾動條信息

iScroll存儲了很多有用的信息脱拼，您可以使用它們來增強應(yīng)用場景坷备，可以說要用IScroll做一個功能這個信息是必不可少的省撑。

最常用到的信息有

• myScroll.x / y 當前位置

• myScroll.directionX / Y 最后的方向（-1 down / right，0 still娃惯，1 up / left）

• myScroll.currentPage 當前對齊捕獲點

在回調(diào)中趾浅，通過this就可獲取到所有的滾動條信息拙吉。

myScroll = new IScroll('#wrapper');
myScroll.on('scrollEnd', function () {
    if ( this.x < -1000 ) {
        // do something
    }
});

銷毀

在不需要使用iScoll的時候調(diào)用iScroll實例的公共方法destroy()可以釋放一些內(nèi)存筷黔。

myScroll.destroy();
myScroll = null;