iScroll 4.2.5 中文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-4

更新:2012.07.14

版本:v4.2.5

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

iScroll的歷史

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

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

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

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

iScroll 4 新特性

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

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

快速上手

使用指南

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

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的本地化應用出現了這個效果之后,這個效果就變得非常流行,你可以點擊這里(需要翻牆)看看視頻先一睹為快,也可以點擊這里試試拉動刷新是如何工作的。

實現原理

  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改變后自動刷新
 
 
   


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM