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的本地化应用出现了这个效果之后,这个效果就变得非常流行,你可以点击这里(需要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上测试的时候似乎没效果,不知道是我测试方法错了还是怎么回事。

 

各种效果的实现

滚动刷新


‘Pull to refresh’ demo

这个效果已经应用在Twitter app上和许多苹果应用上使用。

最新版中,作者把滚动刷新和代码复制的功能写成了一个外部插件,可查看DEMO看它是如何工作的。

只需要定义一个pullDownAction()函数,通过ajax来调取数据,然后用refresh方法刷新DOM。请注意增加1秒的延迟来模拟网络阻塞。

 

放大/缩小


‘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元素


‘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’。

 

自定义滚动条


‘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改变后自动刷新
 
 
   

你可能感兴趣的:(scroll)