iScroll 4 使用详解

原文：http://cubiq.org/iscroll-4

iScroll终于迎来了一个彻底的重写。现在的效果比以往更平滑并且增加了一些新的特性：缩放、下拉式刷新、元素捕捉以及更多更高级别可编程性的自定义事件。

项目信息

最后一次代码更新：2012.07.14 – v4.2
设备兼容：iPhone/Ipod touch >=3.1.1, iPad >=3.2, Android >=1.6, Desktop Webkit, Firefox, Opera desktop/mobile.

概述

iScroll 4是对于原始iScroll代码的一个彻底的重写，该脚本之所以开发是因为手机webkit客户端(包括 iPhone, iPad, Android)不提供原生的方式支持在一个固定宽度／高度元素内的内容滚动。
不幸的是这阻止织了任何的web-app有一个绝对定位的 头部或底部和滚动的中央区域的内容。

最新版本的Android已经支持了这个功能（尽管支持的还不够理想），而Apple似乎不愿意为div添加一个手指滚动的功能。

除了前面所介绍的iScroll产品特点，这一版本还有如下特点：

• 缩放
• 上拉/下拉刷新
• 速度和性能的提升
• 元素捕捉
• 自定义滚动条

请注意iScroll 4不是iScroll 3的简单升级，它的API已经完全改变了。

同时考虑到该脚本仍然处于测试阶段,一些API可能会略有变化。

入门指南

演示demo

在这份文档中你会找到大量的例子来让你快速上手，在寻求帮助前，请先看下demo演示并通读所有的文档。我知道这有些无聊，但它掌握了所有关于 iScroll忍者的秘密。

iScroll需要初始化每一个你要滚动的区域，在不考虑你的设备内存及CPU的前提下，不限制在任意单个页面上的iScroll滚动数量。内容的类型和长度将影响你能够同时使用的iScoll的数量。

尽可能的保持DOM结构简单，删除所有不必要的标记和避免过多的嵌套元素。

最佳的iScroll结构：

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

在这个例子中，UL元素会滚动。iScroll必须应用在滚动区域的包装容器上。

重要：只有包装容器元素的第一个子元素会滚动，如果你想要滚动更多的元素可以试试以下的结构：

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

		<ul>
			<li></li>
			...
			...
		</ul>
	</div>
</div>

在这个例子中，scroller元素可以滚动。（连同两个ul元素一起）

iScroll必须在DOM就绪后实例化（ie：第一次调用），主要有以下几种方法：

• onDOMContentLoaded事件
• onLoad事件
• 以内联方式将代码放到你想要滚动的html代码后面

onDOMContentLoaded

如果要滚动的内容只包含文字和固定尺寸的图片，你可以使用nDOMContentLoaded事件。

在文档头部添加：

<script type="application/javascript" src="iscroll.js"></script>
<script type="text/javascript">
var myScroll;
function loaded() {
	myScroll = new iScroll('wrapper');
}
document.addEventListener('DOMContentLoaded', loaded, false);
</script>

注意，这里的myScroll变量是全局的，所以你可以在任何地方调用这个滚动条函数。

onLoad

有时候在内容还没准备好（DOM未加载完毕）的情况下使用onDOMContentLoaded显得有点仓促草率，如果你遇到一些奇怪的行为（如橡皮筋效果），请尝试以下的方法：

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

在这种情况下，iScroll只有在页面（包括图片）加载完毕后的100ms之后初始化，这应该是一种比较安全的调用iScroll的方式。这可能是hi最安全的iScroll调用方式。

内联初始化

使用这种方法，一旦包装容器和它的内容被写入页面以后，iScroll就进行初始化。我不建议使用这种方法，但是很多javascript专家使用它，难道我还能不同意？

首先在页面的HEAD内包含iscroll.js文件，然后在滚动内容后创建iScroll对象。

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

<script type="text/javascript">
var myScroll = new iScroll('wrapper');
</script>

或者你可以使用你喜欢的框架ready方法，例如:jquery ready()。

iScroll传递参数

你可以用可选的第二个参数来自定义一些iScroll行为。例如：

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

第二个参数始终是一个对象。在上面的例子中的滚动条不会显示，一些常用的参数如下：

• hScroll，用于在任何情况下禁止水平滚动，默认情况下你可以在水平和垂直方向上滚动，当内容超出包装容器大小时，你可以通过将该参数设未false来禁止水平方向的滚动。
• vScroll, 同上，垂直滚动。
• hScrollbar，设置为false,以防止出现水平滚动条。
• vScrollbar，同上，垂直滚动条。
• fixedScrollbar，在iOS上当你拖动滚动条的边界时滚动条可能会收缩。设置这个为true，以防止滚动条移动到可见区域的范围以外（如同Android），默认：Android上为false，iOS上为true。
• fadeScrollbar，设为false，使得滚动条在消失的时候没有渐隐效果。
• hideScrollbar，在没有用户交互时，滚动条淡出消失，你可能想让他们总是可见。默认值:true。
• bounce，启用／禁用边界反弹效果。默认：true。
• momentum，启用／禁用惯性效果。默认：true。如果你想保存资源时有用。
• lockDirection，当你开始拖动一个轴而另一个被锁定，保持拖动只在两个方向（上/下或左/右），你可以通过设置该参数为false来删除方向锁定。

技巧：为了保护资源，请尝试去除滚动条（水平或垂直方向）。

下拉刷新

演示demo

该功能之所以变的著名这要归功于twitter以及其他更多的Apple Store上的原生应用。你可以在这里看预览。我最近将”pull to refresh”从核心脚本种删除，并且复制相同的功能到外部插件。请看所包含的示例，以了解它是如何工作的。

你所必须做的就是自定义pullDownAction()函数，你可能需要一个Ajax调用加载新的内容，记得一旦有新数据添加到DOM，调用 refresh方法，还请注意，在示例中我们添加了1秒的延迟来模拟网络阻塞。当然如果你不想要这个效果，记得删除setTimeout方法。

缩放

演示demo

让我们面对这样一个事实：单纯滚动其实很无聊。这就是为什么iScroll 4支持放大和缩小，通过设置缩放选项设置为true，来实现利用手势进行放大和缩小。请相信你的眼睛如果你不相信我。

双击放大缩小也得到支持。

最低设置启用缩放功能：

var myScroll = new iScroll('wrapper', { zoom: true });

你可以通过以下选项自定义缩放行为：

• zoomMax，指定允许的最大比例。默认是4，意味着原始大小的4倍。

技巧：如果想要好的缩放图像效果可以把它们放置到硬件合成层。通俗一点说，在所有需要缩放的img元素上应用用-webkit-transform:translate3d(0,0,0) ，

重要：别说我没提醒过你－硬件加速需要消耗大量的资源，保守使用否则应用程序就会崩溃。

元素捕捉

演示demo

捕捉功能可锁定滚动条预先确定的位置。这可以用来创建花哨的幻灯片轮播效果。

默认情况下iScroll把滚动条分为相同大小包装容器的页面或象限。iScroll 4也添加选项来捕捉滚动条内的任何元素，无论包装容器尺寸如何。

如果希望创建幻灯片轮播效果，我建议使用默认的“象限”划分 。完美的设置如下：

var myScroll = new iScroll('wrapper', {
	snap: true,
	momentum: false,
	hScrollbar: false,
	vScrollbar: false });

为了捕捉到元素，通过一个字符串来表示滚动条应当捕捉到的DOM元素的查询。例如：

var myScroll = new iScroll('wrapper', {
	snap: 'li',
	momentum: false,
	hScrollbar: false,
	vScrollbar: false });

在这个例子中滚动条将捕捉到滚动区域中所有li元素的左上角。

请注意该捕捉字符串被应用于scroller（ie:scroller.querySelectorAll(snap_string)），所以，“＃scroller li”是错误的，只有“li” 是正确的。

自定义滚动条

演示demo

现在，你可以通过用一系列的css来自定义滚动条的外观，只需要通过scrollbarClass属性，设定一个class给你的滚动条：

myScroll = new iScroll('wrapper', { scrollbarClass: 'myScrollbar' });

在这个例子中，myScrollbarH的类将被应用于水平导航条而myScrollbarV被用于垂直导航条。需要注意的是 ，滚动条由两个元素组成：容器和指示器。容器具有和滚动条包装容器相同的高度，而指示器则是滚动条本身。

滚动条HTML结构：

<div class="myScrollBarV">
	<div></div>
</div>

CSS样式:(demo)

.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);
}

公共方法

iScroll有一些公共的方法，你可以在任何时间对滚动条施加影响。最重要的一条是refresh，当每次滚动内容改变时被调用。

公共方法的访问要归功于全局变量对iScroll初始化的作用，在这个例子中我使用myScroll，你可以访问所有的方法通过：

myScroll.name_of_the_function(parameters)

继续阅读更详细的内容

掌握refresh()方法

iScroll需要知道包装容器和滚动区域的正确大小，它们只在第一次启动时计算，如果你的代码改变了元素的大小，iScroll需要被告知到。

这是调用refresh()函数进行访问的好时机，请紧跟着我了解这块的知识，能让你节省尝试滚动失败的时间。

每次当你改变元素的宽／高度或者你以任何方式改变html的结构时(例如：appendChild 或 innerHTML)，浏览器会重新渲染页面。一旦浏览器应用了改变，你可以通过javascript访问新的DOM结构（及属性）。有时这个过程不是实时的。

确保javascript得到更新的参数，迫使你去访问经过重新实例化后的DOM。看看下面的代码：

ajax('page.php', onCompletion);

function onCompletion () {
	// Here modify the DOM in any way, eg: by adding LIs to the scroller UL
	
	setTimeout(function () {
		myScroll.refresh();
	}, 0);
};

这里我们设置了一个零延时的刷新调用。使得浏览器自己刷新的同时保证新元素的正确尺寸。还有其他方法来确保浏览器实际更新了DOM，但到目前为止，零延时被证明是最稳定的。

所以黄金法则是：如果不确定 请在超时范围内进行刷新

javascript滚动

你可以通过scrollTo, scrollToElement和scrollToPage三个方法来控制滚动效果（如果你使用snap属性）。

scrollTo(x, y, time, relative) 方法让滚动区域内容在指定的时间内滚动到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)。滚动到列表的第10个元素，第一个参数是一个CSS3选择器或元素节点本身。

如果spap属性被激活，你也可以使用snapToPage(pageX, pageY, time)方法：myScroll.scrollToPage(1, 0, 200)。在200毫秒内从第1页滚动到第2页（0代表第1页，1代表第2页）

销毁实例

如果要完全销毁iScroll实例及释放一些内存空间，请调用destory()方法。

最好的销毁方式：

myScroll.destroy();
myScroll = null;

Lite版iScroll

iScroll针对基本的滚动功能，做了改进化并添加许多新的特性，如果你只希望在移动设备中使用iScroll，你最好使用iscroll-lite.js替代。

iScroll Lite 是 iScroll 4的精简版。它仅支持在移动设备上的滚动（不兼容桌面）。捕捉、缩放、下拉刷新等功能都被剥离。尽可能的减少资源占用。

已知问题和未来的发展

以下是目前已知的问题：

• 表单域兼容
• 缩放的一些小问题
• 好的桌面浏览器兼容
• onScroll事件
• 散列和散列值改变的支持
• 当DOM变化后自动刷新

原创译文 转载请注明出处：http://www.yingxiangzhi.com/blog/?p=1434
英文原文：http://cubiq.org/iscroll-4