iScroll 4 API

概況

資料來源

  1. http://cubiq.org/iscroll-4
  2. http://www.cnblogs.com/wanghun/archive/2012/10/17/2727416.html
  3. http://qbaty.iteye.com/blog/1221061

iScroll基本信息

官網:http://cubiq.org/iscroll-4javascript

更新:2012.07.14php

版本:v4.2.5css

兼容:iPhone/Ipod touch >=3.1.1, iPad >=3.2, Android >=1.6, Desktop Webkit, Firefox, Opera desktop/mobile.html

iScroll的歷史

之因此iscroll會誕生,主要是由於不管是在iphone、ipod、android 或是更早前的移動webkit都沒有提供一種原生的方式來支持在一個固定高度的容器內滾動內容。java

這個不幸的規則致使全部web-app要模擬成app的樣子時,只能由一個絕對定位的header 或是footer再加上一個能夠內容的滾動的中間區域組成。jquery

幸運的是移動webkit提供了一種強大的硬件加速的CSS屬性,這個屬性能夠用來模擬這個缺失的功能,Iscroll從這裏開始了前進之路,可是沒有不帶刺的玫瑰。讓內容滾動像原生方式通常比想象中要難android

Tigs:截至2013年,IOS5 添加以下樣式 overflow:scroll; -webkit-overflow-scrolling:touch; 已經可以支持區域滾動了。可是andriod4 仍是不行...

iScroll 4 新特性

iScroll 4 這個版本徹底重寫了iScroll 3這個框架的原始代碼,除了之前版本的iScroll特性之外,iScroll 4 還包括以下的特性:web

  1. 縮放
  2. 拉動刷新
  3. 速度和性能提高
  4. 精確捕捉元素
  5. 自定義滾動條

快速上手

使用指南

在此文檔中你會發現不少例子來教會你如何快速上手iScroll腳本庫。參看文中的demo小例子並仔細閱讀此文檔,可能有點小無聊,可是這篇文章中倒是iScroll這個腳本庫的精髓之所在哦。ajax

iScroll須要對所要進行滾動的元素進行初始化,而且不限定一個頁面中使用iScroll的元素的個數(這裏不考慮您的硬件配置)。滾動元素中內容的類型和長度在必定程度上將會影響iScroll腳本庫裏能夠同時使用的元素的個數。編程

使用iScroll這個腳本庫時,DOM樹的結構要足夠簡單,移除沒必要要的標籤,儘可能避免過多的標籤嵌套使用。

最優的使用iScroll的結構以下所示:

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

在這個小例子中,ul標籤將會被滾動。iScroll必定要與滾動內容外面的wrapper進行聯繫纔會產生效果。

注意事項

只有wrapper裏的第一個子元素才能夠滾動,若是你想要更多的元素能夠滾動,那麼你能夠試試下面的這種寫法:

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

在這個例子中,scroller這個元素能夠滾動,即使它包含兩個ul元素

實例化iScroll

iScroll必須在調用以前實例化,你能夠在下面幾種狀況下對iScroll進行實例化:

  1. onDOMContentLoaded
  2. onLoad
  3. 之內聯inline方式

ONDOMContentLoaded

適用於滾動內容只包含文字、圖片,而且全部的圖片都有固定的尺寸

使用方法:(在head標籤中添加以下代碼)

	<script src="iscroll.js"></script>
	<script>
			var myscroll;
			function loaded(){
				myscroll=new iScroll("wrapper");
			}
			window.addEventListener("DOMContentLoaded",loaded,false);
	</script>
注意: myscroll這個變量是全局的,所以你能夠在任何地方調用它的函數

onLoad

有些時候在DOMContentLoaded的狀態下就初始化iScroll實際上是有點草率的,所以此時頁面的資源可能尚未所有加載完畢。若是你遇到了一些很怪異的行爲能夠試試下面的寫法:

	<script src="iscroll.js"></script>
	<script>
		var myscroll;
		function loaded(){
			setTimeout(function(){
				myscroll=new iScroll("wrapper");
			},100 );
		}
		window.addEventListener("load",loaded,false);
	</script>

這種狀況下iScroll會在頁面資源(包括圖片)加載完畢100ms以後獲得初始化,這應該是一種比較安全的調用iScroll的方式。

inline初始化

這種狀況會在頁面加載到js的時候就進行調用,此方法不推薦使用,可是不少javascript的大牛都在用這種方式,我又 有什麼理由不同意呢?

	<script src="iscroll.js"></script>
	<div id="wrapper">
		<ul>
			<li></li>
			.....
		</ul>
	</div> 
	<script>
		var myscroll=new iScroll("wrapper");
	</script>

不過建議你使用一些框架的ready方法來安全調用iScroll(好比jquery裏的ready())。

iScroll 參數

iScroll裏的第一個參數很簡單就是外容器的id,或者css語法格式的class,如'.home .scroll'。

第二個參數容許你自定義一些屬性配置和方法,好比下面的這段代碼:

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

第二個參數一般都是一個對象,像上面的這個例子裏就設定了不顯示滾動條。全部參數以下(*號爲常見參數):

基本參數
參數名 說明 可選值 默認值
hScroll * 是否容許水平滾動 false 否 true 是 true
vScroll * 是否容許垂直滾動 false 否 true 是 true
bounce * 是否超過實際位置反彈 false 否 true 是 true
bounceLock 當內容少於滾動是否能夠反彈 false 否 true 是 false
momentum * 是否開啓拖動慣性 false 否 true 是 true
lockDirection 當水平或垂直拖動時是否鎖定另外一邊的拖動 false 否 true 是 true
useTransform 是否使用CSS變形 false 否 true 是 true
useTransition 是否使用CSS變換 false 否 true 是 false
checkDOMChanges 是否自動檢測內容變化 false 否 true 是 false
topOffset 已經滾動的基準值(通常用在拖動刷新) 數字值 0
x 滾動水平初始位置(負值) 數字值 0
y 滾動垂直初始位置(負值) 數字值 0
Scrollbar 的相關參數
參數名 說明 可選值 默認值
hScrollbar * 是否顯示水平滾動條 false否 true true
vScrollbar * 是否顯示垂直滾動條 false否 true true
fixedScrollbar 在iOS系統上,當元素拖動超出了scroller的邊界時,滾動條會收縮,設置爲true能夠禁止滾動條超出scroller的可見區域。 false否 true 默認在Android上爲true, iOS上爲false
hideScrollbar 是否隱藏滾動條 false否 true 默認在Android上爲false, iOS上爲true
fadeScrollbar 滾動條是否漸隱漸顯 false否 true 默認在Android上爲false, iOS上爲true
scrollbarClass* 字定義滾動條的樣式名 自定義class ''
Zoom 放大相關的參數
參數名 說明 可選值 默認值
zoom 是否放大 false 否 true 是 false
zoomMin 放大的最小倍數 數字值 1
zoomMax 放大的最大倍數 數字值 4
doubleTapZoom 雙擊放大倍數 數字值 2
wheelAction 鼠標滾動行爲(還能夠是zoom) none 不支持 'scroll' 鼠標滾動 'zoom' 鼠標縮放 'scroll'
snap 捕捉元素相關的參數
參數名 說明 可選值 默認值
snap 是否開啓捕捉元素,snap值能夠爲true 或是 DOM元素的tagname,當爲true 時,捕捉的元素會根據可滾動的位置和滾動區域計算獲得可滑動幾頁。若是爲tagname,則滑動會對齊到捕捉的元素上。 false 否true 是< DOM元素的tagname false
snapThreshold 滑動的長度限制,只有大於這個距離纔會觸發捕捉元素事件 數字值 1
自定義 Events 的相關參數
參數名 說明 可選值 默認值
onBeforeScrollStart 開始滾動前的事件回調
默認是阻止瀏覽器默認行爲
null 不設置 
Function 自定義函數
function (e) { e.preventDefault(); }
onRefresh refresh 的回調 null
onScrollStart 開始滾動的回調
onBeforeScrollMove 在內容移動前的回調
onScrollMove 內容移動的回調
onBeforeScrollEnd 在滾動結束前的回調
onScrollEnd 在滾動完成後的回調
onTouchEnd 手離開屏幕後的回調
onDestroy 銷燬實例的回調
onZoomStart 放大開始時的回調
onZoom 放大的回調
onZoomEnd 放大結束後的回調

iScroll 方法API

destroy

銷燬你實例化的iScroll 實例,包括以前綁定的全部iscroll 事件。

refresh

這個方法很是有用,當你的滾動區域的內容發生改變 或是 滾動區域不正確,都用經過調用refresh 來使得iscroll 從新計算滾動的區域,包括滾動條,來使得iscroll 適合當前的dom。

scrollTo

這個方法接受4個參數 x, y, time, relative x 爲移動的x軸座標,y爲移動的y軸座標, time爲移動時間,relative表示是否相對當前位置。

scrollToElement

這個方法其實是對scrollTo的進一步封裝,接受兩個參數(el,time),el爲須要滾動到的元素引用,time爲滾動時間。

scrollToPage

此方法接受三個參數(pageX,pageY,time) 當滾動內容的高寬大於滾動範圍時,iscroll 會自動分頁,而後就能使用scrollToPage方法滾動到頁面。固然,當hscroll 爲false 的時候,不能左右滾動。pageX這個參數就失去效果

disable

調用這個方法會當即中止動畫滾動,而且把滾動位置還原成0,取消綁定touchmove, touchend、touchcancel事件。

enable

調用這個方法,使得iscroll恢復默認正常狀態

stop

當即中止動畫

zoom

改變內容的大小倍數,此方法接受4個參數,x,y,scale,time 分別表示的意思爲,放大的基準座標,以及放大倍數,動畫時間

isReady

當iscroll 沒有處於正在滾動,沒有移動過,沒有改變大小時,此值爲true

拉動刷新

說明

自從Twitter和一些Apple的本地化應用出現了這個效果以後,這個效果就變得很是流行,你能夠點擊這裏(須要FQ)看看視頻先一睹爲快,也能夠點擊這裏試試拉動刷新是如何工做的。

實現原理

  1. 經過 topOffset 參數屬性設置iScroll已經滾動的基準值;
  2. 經過 onScrollMove 參數方法判斷當前滾動是到頂端仍是底端;
  3. 經過 onScrollEnd 參數方法觸發加載新數據,再經過 refresh 方法從新渲染界面;
  4. 經過 onRefresh 參數方法調整刷新後的界面結構;
	<script>
		var myScroll =new iScroll("wrapper",{
			topOffset: 50,
			onRefresh: function(){...},
			onScrollMove: function(){...},
			onScrollEnd: function()...{}
		});
	</script>

具體的實現代碼能夠查看這裏的源文件;

縮放

咱們不得不面對一個事實,那就是光有滾動其實沒什麼新意的。這就是爲何在iScroll 4這個版本里咱們容許你能夠放 大和縮小。想要這個功能,只須要設置放大的參數zoom 爲true便可實現利用手勢來放大和縮小。你能夠看看這兒。

雙擊放大和縮小的功能在iScroll 4裏也是獲得支持的。要使用縮放功能,你至少須要以下配置:

	<script>
		var myScroll =new iScroll("wrapper",{zoom:true});
	</script>

若是你想對縮放功能進行深度的自定義的話可使用下面的一些選項:

參數名 說明
zoomMax 指定容許放大的最大倍數,默認爲4
【注意事項】: 若是想要圖片縮放的效果很好的話要把他們放到硬件的合成層中。通俗點說,就是在全部須要縮放的img元素上使用-webkit-transform:translate3d(0,0,0)來實現,並且尤其重要的是,硬件的加速會佔用大量資源,要謹慎使用,不然你的應用可能就此崩潰。

捕捉元素

捕捉的功能會促使scroller去從新定義位置,這樣能夠製做更加花哨的傳送帶效果。點擊這裏有個小例子。

默認狀況下,iScroll將scroller分紅四分體,或者是相同大小的wrapper。iScroll 4加入了這個屬性容許捕捉scroller裏的任何元素,不考慮外部wrapper的大小。若是你想要實現這樣的傳送帶效果,我建議你使用「quadrant」分割。最佳的設置以下:

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

捕獲元素,能夠經過傳遞一個字符串來做爲查詢條件,以下:

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

在這個例子中scroller能夠捕捉到滾動區域中最左上角的li元素

自定義滾動條

在iScroll 4這個版本中,能夠利用一系列的css來自定義滾動條的呈現。能夠給滾動條添加一個class參數,以下:

	<script>
		var myscroll=new iScroll("wrapper",{
			scrollbarClass: "myScrollbar"
		});
	</script>

你能夠點擊這裏看一個小例子,在這個小例子裏,myScrollbarH這個類被添加到了水平滾動條上,myScrollbarV這個類則被添加給了垂直方向上的滾動條上了。須要提醒的是,滾動條是由兩個元素組合而成的:容器和顯示器。容器同wrapper的高度相同,而顯示器則表明的是滾動條自己。

滾動條的HTML結構以下:

	<div class="myScrollbarV">
		<div></div>
	</div>

	.myscrollbarV{
		position:absolute;z-index:100;width:8px;bottom:7px;top:2px;right:1px;
	}

	.myScrollbarV > div {
		position:absolute;
		z-index:100;
		width:100%;
		/* The following is probably what you want to customize */
		background:-webkit-gradient(linear, 0 0, 100% 0, from(#f00), to(#900));
		border:1px solid #800;
		-webkit-background-clip:padding-box;
		-webkit-box-sizing:border-box;
		-webkit-border-radius:4px;
		-webkit-box-shadow:inset 1px 1px 0 rgba(255,255,255,0.5);
	}
 
 

移動設備web開發插件iScroll的使用詳解

iScroll是一款用於移動設備web開發的一款插件。像縮放、下拉刷新、滑動切換等移動應用上常見的一些效果均可以輕鬆實現。

iScroll的最新版本是2011.07.03發佈的4.1.7版。最新版比以往更順暢,添加了更多的自定義事件,提供了更高級的可編程性。

使用方法:

DOM結構應儘可能保持簡潔,避免過多的嵌套。滾動區域爲第一個子元素。html代碼:

?
1
2
3
4
5
6
7
< div  id = "wrapper" >
     < ul >
         < li ></ li >
         ...
         ...
     </ ul >
</ div >

上面的DOM結構中,ul將是滾動的區域。若是想同時滾動多個區域就要用一個容器把須要滾動的區域包起來。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
< div  id = "wrapper" >
     < div  id = "scroller" >
         < ul >
             < li ></ li >
             ...
             ...
         </ ul >
         < ul >
             < li ></ li >
             ...
             ...
         </ ul >
     </ div >
</ div >

上面的DOM結構中,兩個UL會同時滾動。

插件的調用須要在頁面徹底加載以後。你能夠經過如下3種方法來實現。

  • 設置onDOMContentLoaded事件
  • 設置onLoad事件
  • 把調用代碼放到頁面的最後。

使用onDOMContentLoaded事件實現滾動

若是滾動區域的長寬是固定的,就能夠經過onDOMContentLoaded事件來實現滾動。

?
1
2
3
4
5
6
7
8
<script type= "application/javascript"  src= "/Admin/News/edit/id/iscroll.js" ></script>
<script type= "text/javascript" >
     var  myScroll;
     function  loaded() {
         myScroll =  new  iScroll( 'wrapper' );
     }
     document.addEventListener( 'DOMContentLoaded' , loaded,  false );
</script>

注意:變量myScroll是全局的,能夠在任什麼時候候調用插件。

使用onLoad事件實現滾動

由於DOMContentLoaded事件是載入DOM結構後就會被調用,因此在圖片等元素未載入前可能沒法肯定滾動區域的長寬,此時可使用onLoad事件來實現。

?
1
2
3
4
5
6
7
8
9
10
     <script type= "application/javascript" src= "/Admin/News/edit/id/iscroll.js" ></script>
<script type= "text/javascript" >
     var  myScroll;
     function  loaded() {
         setTimeout( function  () {
             myScroll =  new  iScroll( 'wrapper' );
         }, 100);
     }
     window.addEventListener( 'load' , loaded,  false );
</script>

如上代碼,在頁面加載完100毫秒後調用插件。若是這個時間後還有元素未徹底載入致使沒法計算滾動區域長寬,可能會致使錯誤。但這是目前最好的方法了。

把調用的代碼放到最後

?
1
2
3
4
5
6
7
8
9
10
< div  id = "wrapper" >
     < ul >
         < li ></ li >
         ...
         ...
     </ ul >
</ div >
< script  type = "text/javascript" >
var myScroll = new iScroll('wrapper');
</ script >

不少javascript大師推薦用這種方法來實現一些須要先加載DOM的特效。所以,在此也可使用這個方法。但插件開發者彷佛並不推薦。由於有可能會出現執行javascript以前沒有徹底載入頁面元素,好比圖片。

ISCROLL參數設置

在實例化的時候能夠經過傳遞第二個參數來設置一些效果。

?
1
2
3
<script type= "text/javascript" >
var  myScroll =  new  iScroll( 'wrapper' , { hScrollbar:  false , vScrollbar:  false });
</script>

第2個參數是以對象的形式傳遞的。如上代碼中爲效果爲隱藏滾動條。參數以下:

  • hScroll:不管內容是否超出顯示區域,都禁用水平方向的滾動條。默認狀況下是水平和垂直方向同時出現的。
  • vScroll:禁用垂直方向的滾動條。
  • hScrollbar:隱藏水平方向的滾動條。
  • vScrollbar:隱藏垂直方向的滾動條。
  • fixedScrollbar:在IOS中拖動滾動條的時候可能會使內容(或滾動條,)縮小,設置該參數爲true可防止該現象。一樣適用於Android。Android默認爲true,IOS默認爲FALSE。
  • hideScrollbar:在用戶沒有操做的時候是否隱藏滾動條。默認爲false
  • fadeScrollbar:設置滾動條的談入談出效果。在hideScrollbar爲true的時候有效
  • bounce:設置滾動條邊界的時候是否有反彈效果,默認爲true。
  • momentum:設置是否開始慣性,關閉此效果可節省資源
  • lockDirection:保持只在兩個方向上或滾動(上/下或左/右),在翻屏的時候可以使用。不過我在Android上測試的時候彷佛沒效果,不知道是我測試方法錯了仍是怎麼回事。

 

各類效果的實現

滾動刷新

web開發技術
‘Pull to refresh’ demo

這個效果已經應用在Twitter app上和許多蘋果應用上使用。

最新版中,做者把滾動刷新和代碼複製的功能寫成了一個外部插件,可查看DEMO看它是如何工做的。

只須要定義一個pullDownAction()函數,經過ajax來調取數據,而後用refresh方法刷新DOM。請注意增長1秒的延遲來模擬網絡阻塞。

 

放大/縮小

web開發技術
‘Zoom’ example

經過這個插件,還能夠實現滾動區域兩指縮放的效果。也能夠經過雙擊來實現縮放。

在第二個參數加添加zoom參數爲true就能夠實現,經過對zoomMax參數還能夠控制縮放的倍數,最大值爲4倍

var myScroll = new iScroll(‘wrapper’, { zoom: true,zoomMax:4});

這個效果是經過硬件加速或使用webkit內核的 -webkit-transform:translate3d(0,0,0)的動畫CSS3屬性來實現。

注意:硬件加速須要消耗大量的資源,有可能會使系統崩潰。

 

SNAP和SNAP元素

web開發技術
‘Carousel’ demo

SNAP功能是判斷元素是否滑動到指定位置。經過這個效果能夠製做花哨的跑馬燈效果。

插件會自動分析滾動區域內相同標籤或相同大小的元素作爲捕捉對象,也能夠經過參數指定捕捉的對象

?
1
2
3
4
5
var  myScroll =  new  iScroll( 'wrapper' , {
snap:  true ,
momentum:  false ,
hScrollbar:  false ,
vScrollbar:  false  });

能夠經過設置snap參數爲指定標籤來設定捕捉對象。好比捕捉li標籤。

?
1
2
3
4
5
var  myScroll =  new  iScroll( 'wrapper' , {
snap:  'li' ,
momentum:  false ,
hScrollbar:  false ,
vScrollbar:  false  });

在snap屬性的值爲指定標籤的時候,插件會經過 scroller.querySelectorAll(snap_string)的方法來獲取對象。因此要注意不要寫成」$scroller li」,這是錯誤的。只要寫’li’。

 

自定義滾動條

web開發技術
‘Custom scrollbars’ demo

iScroll插件容許你自定義滾動條的樣式。能夠經過css定義一個class,並經過scrollbarClass屬性把class的名稱傳遞給iScroll就能夠了。

myScroll = new iScroll(‘wrapper’, { scrollbarClass: ‘myScrollbar’ })

滾動條的DOM結構是一個class名爲myScrollBarV的外容器和一個指標組成。能夠經過改變這兩個元素的樣式來自定義滾動條。

?
1
2
3
< div  class = "myScrollBarV" >
< div ></ div >
</ div >
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
.myScrollbarV {
position : absolute ;
z-index : 100 ;
width : 8px ; bottom : 7px ; top : 2px ; right : 1px
}
 
.myScrollbarV > div {
     position : absolute ;
     z-index : 100 ;
     width : 100% ;
     background :-webkit-gradient(linear,  0  0 100%  0 , from( #f00 ), to( #900 ));
     border : 1px  solid  #800 ;
     -webkit-background- clip :padding-box;
     -webkit-box-sizing:border-box;
     -webkit-border-radius: 4px ;
     -webkit-box-shadow: inset  1px  1px  0  rgba( 255 , 255 , 255 , 0.5 );
}

內部方法

iScroll還提供了一些公共方法。好比說refresh。在改變滾動區域裏內容的時候都必須調用refresh方法。由於iScroll是經過實例化一個全局變量來實現的,因此使用者可在任何狀況下調用這些方法。

調用方法: myScroll.name_of_the_function(參數)

refresh方法

iScroll須要知道滾動區域的大小和滾動條才能正常工做。在實例化的時候iScroll會自動計算一次。但若是滾動區域裏的內容發生變化後,須要告訴iScroll內容發生了變化。

每次改變元素的高度/寬度或以任何方式修改(如: appendChild或innerHTML的)HTML結構時,瀏覽器會從新渲染頁面。javascript就須要從新分析新的DOM結構和新的屬性,有時候,這個不是即時的。

爲了確保javascript分析新的頁面,能夠實例化一個新的iScroll。

?
1
2
3
4
5
6
ajax( 'page.php' , onCompletion);
function  onCompletion () {
     setTimeout( function  () {
         myScroll.refresh();
     }, 0);
};

JAVASCRIPT SCROLLING

iScroll還提供了scrollTo, scrollToElement和scrollToPage三個方法讓你可以經過javascript來控制滾動效果。

scrollTo(x, y, time, relative):在指定的time時間內讓內容滾動條x/y的位置。如myScroll.scrollTo(0, -100, 200) 在200毫秒內Y軸向下滾動100像素。 myScroll.scrollTo(0, 10, 200, true)能夠實現相對當前位置在200毫秒內Y軸向上滾動10像素的效果。

scrollToElement(element, time):在指定的時間內滾動到指定的元素。如myScroll.scrollToElement(‘li:nth-child(10)’, 100) 在100毫秒內滾動到第10個li元素的位置。第1個參數能夠用CSS3中的選擇器來篩選元素。

snapToPage(pageX, pageY, time):在200毫秒內從第1頁滾動到第2頁(0表明第1頁,1表明第2頁)。這個使用SNAP功能的時候能夠調用這個函數。

註銷iScroll

經過調用destroy()函數下注銷iScroll來釋放內存。

myScroll.destroy(); myScroll = null;

LITE版iScroll

若是你只但願在移動設備中使用iScroll,請使用iscroll-lite.js

LITE版是一個精簡版,它支持移動設備(沒有桌面兼容性)滾動。所佔的資源更少。

iScroll的發展方向

  • 表單域的支持
  • 縮放的優化
  • 更好的桌面瀏覽器的兼容性
  • onScrol事件的優化
  • 加個哈希值的變化
  • DOM改變後自動刷新
相關文章
相關標籤/搜索